diff options
Diffstat (limited to 'elpa/org-9.5.2/org.info')
| -rw-r--r-- | elpa/org-9.5.2/org.info | 23626 |
1 files changed, 0 insertions, 23626 deletions
diff --git a/elpa/org-9.5.2/org.info b/elpa/org-9.5.2/org.info deleted file mode 100644 index e7074e7..0000000 --- a/elpa/org-9.5.2/org.info +++ /dev/null @@ -1,23626 +0,0 @@ -This is org.info, produced by makeinfo version 6.7 from org.texi. - -This manual is for Org version 9.5. - - Copyright © 2004–2021 Free Software Foundation, Inc. - - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.3 or any later version published by the Free Software - Foundation; with no Invariant Sections, with the Front-Cover Texts - being “A GNU Manual,” and with the Back-Cover Texts as in (a) - below. A copy of the license is included in the section entitled - “GNU Free Documentation License.” - - (a) The FSF’s Back-Cover Text is: “You have the freedom to copy and - modify this GNU manual.” - -INFO-DIR-SECTION Emacs editing modes -START-INFO-DIR-ENTRY -* Org Mode: (org). Outline-based notes management and organizer. -END-INFO-DIR-ENTRY - - -File: org.info, Node: Top, Next: Introduction, Up: (dir) - -The Org Manual -************** - -This manual is for Org version 9.5. - - Copyright © 2004–2021 Free Software Foundation, Inc. - - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.3 or any later version published by the Free Software - Foundation; with no Invariant Sections, with the Front-Cover Texts - being “A GNU Manual,” and with the Back-Cover Texts as in (a) - below. A copy of the license is included in the section entitled - “GNU Free Documentation License.” - - (a) The FSF’s Back-Cover Text is: “You have the freedom to copy and - modify this GNU manual.” - -* Menu: - -* Introduction:: Getting started. -* Document Structure:: A tree works like your brain. -* Tables:: Pure magic for quick formatting. -* Hyperlinks:: Notes in context. -* TODO Items:: Every tree branch can be a TODO item. -* Tags:: Tagging headlines and matching sets of tags. -* Properties and Columns:: Storing information about an entry. -* Dates and Times:: Making items useful for planning. -* Refiling and Archiving:: Moving and copying information with ease. -* Capture and Attachments:: Dealing with external data. -* Agenda Views:: Collecting information into views. -* Markup for Rich Contents:: Compose beautiful documents. -* Exporting:: Sharing and publishing notes. -* Publishing:: Create a web site of linked Org files. -* Citation handling:: create, follow and export citations. -* Working with Source Code:: Export, evaluate, and tangle code blocks. -* Miscellaneous:: All the rest which did not fit elsewhere. -* Hacking:: How to hack your way around. -* History and Acknowledgments:: How Org came into being. -* GNU Free Documentation License:: The license for this documentation. -* Main Index:: An index of Org’s concepts and features. -* Key Index:: Key bindings and where they are described. -* Command and Function Index:: Command names and some internal functions. -* Variable Index:: Variables mentioned in the manual. - -— The Detailed Node Listing — - -Introduction - -* Summary:: Brief summary of what Org does. -* Installation:: Installing Org. -* Activation:: How to activate Org for certain buffers. -* Feedback:: Bug reports, ideas, patches, etc. -* Conventions:: Typesetting conventions used in this manual. - -Document Structure - -* Headlines:: How to typeset Org tree headlines. -* Visibility Cycling:: Show and hide, much simplified. -* Motion:: Jumping to other headlines. -* Structure Editing:: Changing sequence and level of headlines. -* Sparse Trees:: Matches embedded in context. -* Plain Lists:: Additional structure within an entry. -* Drawers:: Tucking stuff away. -* Blocks:: Folding blocks. - -Visibility Cycling - -* Global and local cycling:: Cycling through various visibility states. -* Initial visibility:: Setting the initial visibility state. -* Catching invisible edits:: Preventing mistakes when editing invisible parts. - -Tables - -* Built-in Table Editor:: Simple tables. -* Column Width and Alignment:: Overrule the automatic settings. -* Column Groups:: Grouping to trigger vertical lines. -* Orgtbl Mode:: The table editor as minor mode. -* The Spreadsheet:: The table editor has spreadsheet capabilities. -* Org Plot:: Plotting from Org tables. - -The Spreadsheet - -* References:: How to refer to another field or range. -* Formula syntax for Calc:: Using Calc to compute stuff. -* Formula syntax for Lisp:: Writing formulas in Emacs Lisp. -* Durations and time values:: How to compute durations and time values. -* Field and range formulas:: Formula for specific (ranges of) fields. -* Column formulas:: Formulas valid for an entire column. -* Lookup functions:: Lookup functions for searching tables. -* Editing and debugging formulas:: Fixing formulas. -* Updating the table:: Recomputing all dependent fields. -* Advanced features:: Field and column names, automatic recalculation... - -Hyperlinks - -* Link Format:: How links in Org are formatted. -* Internal Links:: Links to other places in the current file. -* Radio Targets:: Make targets trigger links in plain text. -* External Links:: URL-like links to the world. -* Handling Links:: Creating, inserting and following. -* Using Links Outside Org:: Linking from my C source code? -* Link Abbreviations:: Shortcuts for writing complex links. -* Search Options:: Linking to a specific location. -* Custom Searches:: When the default search is not enough. - -TODO Items - -* TODO Basics:: Marking and displaying TODO entries. -* TODO Extensions:: Workflow and assignments. -* Progress Logging:: Dates and notes for progress. -* Priorities:: Some things are more important than others. -* Breaking Down Tasks:: Splitting a task into manageable pieces. -* Checkboxes:: Tick-off lists. - -TODO Extensions - -* Workflow states:: From TODO to DONE in steps. -* TODO types:: I do this, Fred does the rest. -* Multiple sets in one file:: Mixing it all, still finding your way. -* Fast access to TODO states:: Single letter selection of state. -* Per-file keywords:: Different files, different requirements. -* Faces for TODO keywords:: Highlighting states. -* TODO dependencies:: When one task needs to wait for others. - -Progress Logging - -* Closing items:: When was this entry marked as done? -* Tracking TODO state changes:: When did the status change? -* Tracking your habits:: How consistent have you been? - -Tags - -* Tag Inheritance:: Tags use the tree structure of an outline. -* Setting Tags:: How to assign tags to a headline. -* Tag Hierarchy:: Create a hierarchy of tags. -* Tag Searches:: Searching for combinations of tags. - -Properties and Columns - -* Property Syntax:: How properties are spelled out. -* Special Properties:: Access to other Org mode features. -* Property Searches:: Matching property values. -* Property Inheritance:: Passing values down a tree. -* Column View:: Tabular viewing and editing. - -Column View - -* Defining columns:: The COLUMNS format property. -* Using column view:: How to create and use column view. -* Capturing column view:: A dynamic block for column view. - -Defining columns - -* Scope of column definitions:: Where defined, where valid? -* Column attributes:: Appearance and content of a column. - -Dates and Times - -* Timestamps:: Assigning a time to a tree entry. -* Creating Timestamps:: Commands to insert timestamps. -* Deadlines and Scheduling:: Planning your work. -* Clocking Work Time:: Tracking how long you spend on a task. -* Effort Estimates:: Planning work effort in advance. -* Timers:: Notes with a running timer. - -Creating Timestamps - -* The date/time prompt:: How Org mode helps you enter dates and times. -* Custom time format:: Making dates look different. - -Deadlines and Scheduling - -* Inserting deadline/schedule:: Planning items. -* Repeated tasks:: Items that show up again and again. - -Clocking Work Time - -* Clocking commands:: Starting and stopping a clock. -* The clock table:: Detailed reports. -* Resolving idle time:: Resolving time when you’ve been idle. - -Refiling and Archiving - -* Refile and Copy:: Moving/copying a tree from one place to another. -* Archiving:: What to do with finished products. - -Archiving - -* Moving subtrees:: Moving a tree to an archive file. -* Internal archiving:: Switch off a tree but keep it in the file. - -Capture and Attachments - -* Capture:: Capturing new stuff. -* Attachments:: Attach files to outlines. -* RSS Feeds:: Getting input from RSS feeds. - -Capture - -* Setting up capture:: Where notes will be stored. -* Using capture:: Commands to invoke and terminate capture. -* Capture templates:: Define the outline of different note types. - -Capture templates - -* Template elements:: What is needed for a complete template entry. -* Template expansion:: Filling in information about time and context. -* Templates in contexts:: Only show a template in a specific context. - -Attachments - -* Attachment defaults and dispatcher:: How to access attachment commands -* Attachment options:: Configuring the attachment system -* Attachment links:: Hyperlink access to attachments -* Automatic version-control with Git:: Everything safely stored away -* Attach from Dired:: Using dired to select an attachment - -Agenda Views - -* Agenda Files:: Files being searched for agenda information. -* Agenda Dispatcher:: Keyboard access to agenda views. -* Built-in Agenda Views:: What is available out of the box? -* Presentation and Sorting:: How agenda items are prepared for display. -* Agenda Commands:: Remote editing of Org trees. -* Custom Agenda Views:: Defining special searches and views. -* Exporting Agenda Views:: Writing a view to a file. -* Agenda Column View:: Using column view for collected entries. - -Built-in Agenda Views - -* Weekly/daily agenda:: The calendar page with current tasks. -* Global TODO list:: All unfinished action items. -* Matching tags and properties:: Structured information with fine-tuned search. -* Search view:: Find entries by searching for text. -* Stuck projects:: Find projects you need to review. - -Presentation and Sorting - -* Categories:: Not all tasks are equal. -* Time-of-day specifications:: How the agenda knows the time. -* Sorting of agenda items:: The order of things. -* Filtering/limiting agenda items:: Dynamically narrow the agenda. - -Custom Agenda Views - -* Storing searches:: Type once, use often. -* Block agenda:: All the stuff you need in a single buffer. -* Setting options:: Changing the rules. - -Markup for Rich Contents - -* Paragraphs:: The basic unit of text. -* Emphasis and Monospace:: Bold, italic, etc. -* Subscripts and Superscripts:: Simple syntax for raising/lowering text. -* Special Symbols:: Greek letters and other symbols. -* Embedded LaTeX:: LaTeX can be freely used inside Org documents. -* Literal Examples:: Source code examples with special formatting. -* Images:: Display an image. -* Captions:: Describe tables, images... -* Horizontal Rules:: Make a line. -* Creating Footnotes:: Edit and read footnotes. - -Embedded LaTeX - -* LaTeX fragments:: Complex formulas made easy. -* Previewing LaTeX fragments:: What will this snippet look like? -* CDLaTeX mode:: Speed up entering of formulas. - -Exporting - -* The Export Dispatcher:: The main interface. -* Export Settings:: Common export settings. -* Table of Contents:: The if and where of the table of contents. -* Include Files:: Include additional files into a document. -* Macro Replacement:: Use macros to create templates. -* Comment Lines:: What will not be exported. -* ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding. -* Beamer Export:: Producing presentations and slides. -* HTML Export:: Exporting to HTML. -* LaTeX Export:: Exporting to LaTeX and processing to PDF. -* Markdown Export:: Exporting to Markdown. -* OpenDocument Text Export:: Exporting to OpenDocument Text. -* Org Export:: Exporting to Org. -* Texinfo Export:: Exporting to Texinfo. -* iCalendar Export:: Exporting to iCalendar. -* Other Built-in Back-ends:: Exporting to a man page. -* Advanced Export Configuration:: Fine-tuning the export output. -* Export in Foreign Buffers:: Author tables and lists in Org syntax. - -Beamer Export - -* Beamer export commands:: For creating Beamer documents. -* Beamer specific export settings:: For customizing Beamer export. -* Frames and Blocks in Beamer:: For composing Beamer slides. -* Beamer specific syntax:: For using in Org documents. -* Editing support:: Editing support. -* A Beamer example:: A complete presentation. - -HTML Export - -* HTML export commands:: Invoking HTML export. -* HTML specific export settings:: Settings for HTML export. -* HTML doctypes:: Exporting various (X)HTML flavors. -* HTML preamble and postamble:: Inserting preamble and postamble. -* Quoting HTML tags:: Using direct HTML in Org files. -* Headlines in HTML export:: Formatting headlines. -* Links in HTML export:: Inserting and formatting links. -* Tables in HTML export:: How to modify the formatting of tables. -* Images in HTML export:: How to insert figures into HTML output. -* Math formatting in HTML export:: Beautiful math also on the web. -* Text areas in HTML export:: An alternate way to show an example. -* CSS support:: Changing the appearance of the output. -* JavaScript support:: Info and folding in a web browser. - -LaTeX Export - -* LaTeX/PDF export commands:: For producing LaTeX and PDF documents. -* LaTeX specific export settings:: Unique to this LaTeX back-end. -* LaTeX header and sectioning:: Setting up the export file structure. -* Quoting LaTeX code:: Incorporating literal LaTeX code. -* Tables in LaTeX export:: Options for exporting tables to LaTeX. -* Images in LaTeX export:: How to insert figures into LaTeX output. -* Plain lists in LaTeX export:: Attributes specific to lists. -* Source blocks in LaTeX export:: Attributes specific to source code blocks. -* Example blocks in LaTeX export:: Attributes specific to example blocks. -* Special blocks in LaTeX export:: Attributes specific to special blocks. -* Horizontal rules in LaTeX export:: Attributes specific to horizontal rules. -* Verse blocks in LaTeX export:: Attributes specific to special blocks. -* Quote blocks in LaTeX export:: Attributes specific to quote blocks. - -OpenDocument Text Export - -* Pre-requisites for ODT export:: Required packages. -* ODT export commands:: Invoking export. -* ODT specific export settings:: Configuration options. -* Extending ODT export:: Producing DOC, PDF files. -* Applying custom styles:: Styling the output. -* Links in ODT export:: Handling and formatting links. -* Tables in ODT export:: Org tables conversions. -* Images in ODT export:: Inserting images. -* Math formatting in ODT export:: Formatting LaTeX fragments. -* Labels and captions in ODT export:: Rendering objects. -* Literal examples in ODT export:: For source code and example blocks. -* Advanced topics in ODT export:: For power users. - -Math formatting in ODT export - -* LaTeX math snippets:: Embedding in LaTeX format. -* MathML and OpenDocument formula files:: Embedding in native format. - -Texinfo Export - -* Texinfo export commands:: Invoking commands. -* Texinfo specific export settings:: Setting the environment. -* Texinfo file header:: Generating the header. -* Texinfo title and copyright page:: Creating preamble pages. -* Info directory file:: Installing a manual in Info file hierarchy. -* Headings and sectioning structure:: Building document structure. -* Indices:: Creating indices. -* Quoting Texinfo code:: Incorporating literal Texinfo code. -* Plain lists in Texinfo export:: List attributes. -* Tables in Texinfo export:: Table attributes. -* Images in Texinfo export:: Image attributes. -* Quotations in Texinfo export:: Quote block attributes. -* Special blocks in Texinfo export:: Special block attributes. -* A Texinfo example:: Processing Org to Texinfo. - -Export in Foreign Buffers - -* Bare HTML:: Exporting HTML without CSS, Javascript, etc. - -Publishing - -* Configuration:: Defining projects. -* Uploading Files:: How to get files up on the server. -* Sample Configuration:: Example projects. -* Triggering Publication:: Publication commands. - -Configuration - -* Project alist:: The central configuration variable. -* Sources and destinations:: From here to there. -* Selecting files:: What files are part of the project? -* Publishing action:: Setting the function doing the publishing. -* Publishing options:: Tweaking HTML/LaTeX export. -* Publishing links:: Which links keep working after publishing? -* Site map:: Generating a list of all pages. -* Generating an index:: An index that reaches across pages. - -Sample Configuration - -* Simple example:: One-component publishing. -* Complex example:: A multi-component publishing example. - -Citation handling - -* Citations:: -* Citation export processors:: - -Working with Source Code - -* Features Overview:: Enjoy the versatility of source blocks. -* Structure of Code Blocks:: Code block syntax described. -* Using Header Arguments:: Different ways to set header arguments. -* Environment of a Code Block:: Arguments, sessions, working directory... -* Evaluating Code Blocks:: Place results of evaluation in the Org buffer. -* Results of Evaluation:: Choosing a results type, post-processing... -* Exporting Code Blocks:: Export contents and/or results. -* Extracting Source Code:: Create pure source code files. -* Languages:: List of supported code block languages. -* Editing Source Code:: Language major-mode editing. -* Noweb Reference Syntax:: Literate programming in Org mode. -* Library of Babel:: Use and contribute to a library of useful code blocks. -* Key bindings and Useful Functions:: Work quickly with code blocks. -* Batch Execution:: Call functions from the command line. - -Miscellaneous - -* Completion:: ‘M-<TAB>’ guesses completions. -* Structure Templates:: Quick insertion of structural elements. -* Speed Keys:: Electric commands at the beginning of a headline. -* Clean View:: Getting rid of leading stars in the outline. -* Execute commands in the active region:: Execute commands on multiple items in Org or agenda view. -* Dynamic Headline Numbering:: Display and update outline numbering. -* The Very Busy C-c C-c Key:: When in doubt, press ‘C-c C-c’. -* In-buffer Settings:: Overview of keywords. -* Regular Expressions:: Elisp regular expressions. -* Org Syntax:: Formal description of Org’s syntax. -* Documentation Access:: Read documentation about current syntax. -* Escape Character:: Prevent Org from interpreting your writing. -* Code Evaluation Security:: Org files evaluate in-line code. -* Interaction:: With other Emacs packages. -* TTY Keys:: Using Org on a tty. -* Protocols:: External access to Emacs and Org. -* Org Crypt:: Encrypting Org files. -* Org Mobile:: Viewing and capture on a mobile device. - -Clean View - -* Org Indent Mode:: -* Hard indentation:: - -Interaction - -* Cooperation:: Packages Org cooperates with. -* Conflicts:: Packages that lead to conflicts. - -Protocols - -* The store-link protocol:: Store a link, push URL to kill-ring. -* The capture protocol:: Fill a buffer with external information. -* The open-source protocol:: Edit published contents. - -Org Mobile - -* Setting up the staging area:: For the mobile device. -* Pushing to the mobile application:: Uploading Org files and agendas. -* Pulling from the mobile application:: Integrating captured and flagged items. - -Hacking - -* Hooks:: How to reach into Org’s internals. -* Add-on Packages:: Available extensions. -* Adding Hyperlink Types:: New custom link types. -* Adding Export Back-ends:: How to write new export back-ends. -* Tables in Arbitrary Syntax:: Orgtbl for LaTeX and other programs. -* Dynamic Blocks:: Automatically filled blocks. -* Special Agenda Views:: Customized views. -* Speeding Up Your Agendas:: Tips on how to speed up your agendas. -* Extracting Agenda Information:: Post-processing agenda information. -* Using the Property API:: Writing programs that use entry properties. -* Using the Mapping API:: Mapping over all or selected entries. - -Tables in Arbitrary Syntax - -* Radio tables:: Sending and receiving radio tables. -* A LaTeX example:: Step by step, almost a tutorial. -* Translator functions:: Copy and modify. - - - -File: org.info, Node: Introduction, Next: Document Structure, Prev: Top, Up: Top - -1 Introduction -************** - -* Menu: - -* Summary:: Brief summary of what Org does. -* Installation:: Installing Org. -* Activation:: How to activate Org for certain buffers. -* Feedback:: Bug reports, ideas, patches, etc. -* Conventions:: Typesetting conventions used in this manual. - - -File: org.info, Node: Summary, Next: Installation, Up: Introduction - -1.1 Summary -=========== - -Org is a mode for keeping notes, maintaining TODO lists, and project -planning with a fast and effective plain-text markup language. It also -is an authoring system with unique support for literate programming and -reproducible research. - - Org is implemented on top of Outline mode, which makes it possible to -keep the content of large files well structured. Visibility cycling and -structure editing help to work with the tree. Tables are easily created -with a built-in table editor. Plain text URL-like links connect to -websites, emails, Usenet messages, BBDB entries, and any files related -to the projects. - - Org develops organizational tasks around notes files that contain -lists or information about projects as plain text. Project planning and -task management make use of metadata which is part of an outline node. -Based on this data, specific entries can be extracted in queries and -create dynamic _agenda views_ that also integrate the Emacs calendar and -diary. Org can be used to implement many different project planning -schemes, such as David Allen’s GTD system. - - Org files can serve as a single source authoring system with export -to many different formats such as HTML, LaTeX, Open Document, and -Markdown. New export backends can be derived from existing ones, or -defined from scratch. - - Org files can include source code blocks, which makes Org uniquely -suited for authoring technical documents with code examples. Org source -code blocks are fully functional; they can be evaluated in place and -their results can be captured in the file. This makes it possible to -create a single file reproducible research compendium. - - Org keeps simple things simple. When first fired up, it should feel -like a straightforward, easy to use outliner. Complexity is not -imposed, but a large amount of functionality is available when needed. -Org is a toolbox. Many users actually run only a—very personal—fraction -of Org’s capabilities, and know that there is more whenever they need -it. - - All of this is achieved with strictly plain text files, the most -portable and future-proof file format. Org runs in Emacs. Emacs is one -of the most widely ported programs, so that Org mode is available on -every major platform. - - There is a website for Org which provides links to the newest version -of Org, as well as additional information, frequently asked questions -(FAQ), links to tutorials, etc. This page is located at -<https://orgmode.org>. - - An earlier version (7.3) of this manual is available as a paperback -book from Network Theory Ltd. -(http://www.network-theory.co.uk/org/manual/). - - -File: org.info, Node: Installation, Next: Activation, Prev: Summary, Up: Introduction - -1.2 Installation -================ - -Org is included in all recent distributions of GNU Emacs, so you -probably do not need to install it. Most users will simply activate Org -and begin exploring its many features. - - If, for one reason or another, you want to install Org on top of this -pre-packaged version, you can use the Emacs package system or clone -Org’s git repository. - - We *strongly recommend* sticking to a single installation method. - -Using Emacs packaging system ----------------------------- - -Recent Emacs distributions include a packaging system which lets you -install Elisp libraries. You can install Org from the “package menu”, -with ‘M-x list-packages’. See *note Package Menu: (emacs)Package Menu. - - Important: You need to do this in a session where no ‘.org’ file - has been visited, i.e., where no Org built-in function have been - loaded. Otherwise autoload Org functions will mess up the - installation. - -Using Org’s git repository --------------------------- - -You can clone Org’s repository and install Org like this: - - $ cd ~/src/ - $ git clone https://git.savannah.gnu.org/git/emacs/org-mode.git - $ cd org-mode/ - $ make autoloads - - Note that in this case, ‘make autoloads’ is mandatory: it defines -Org’s version in ‘org-version.el’ and Org’s autoloads in -‘org-loaddefs.el’. - - Remember to add the correct load path as described in the method -above. - - You can also compile with ‘make’, generate the documentation with -‘make doc’, create a local configuration with ‘make config’ and install -Org with ‘make install’. Please run ‘make help’ to get the list of -compilation/installation options. - - For more detailed explanations on Org’s build system, please check -the Org Build System page on Worg -(https://orgmode.org/worg/dev/org-build-system.html). - -Installing Org’s contributed packages -------------------------------------- - -Org’s repository used to contain ‘contrib/’ directory for add-ons -contributed by others. As of Org 9.5, the directory has bee moved to -this new dedicated org-contrib (https://git.sr.ht/~bzg/org-contrib) -repository, which you can install separately. - - -File: org.info, Node: Activation, Next: Feedback, Prev: Installation, Up: Introduction - -1.3 Activation -============== - -Org mode buffers need Font Lock to be turned on: this is the default in -Emacs(1). - - There are compatibility issues between Org mode and some other Elisp -packages (see *note Conflicts::). Please take the time to check the -list. - - For a better experience, the three Org commands ‘org-store-link’, -‘org-capture’ and ‘org-agenda’ ought to be accessible anywhere in Emacs, -not just in Org buffers. To that effect, you need to bind them to -globally available keys, like the ones reserved for users (see *note -(elisp)Key Binding Conventions::). Here are suggested bindings, please -modify the keys to your own liking. - - (global-set-key (kbd "C-c l") #'org-store-link) - (global-set-key (kbd "C-c a") #'org-agenda) - (global-set-key (kbd "C-c c") #'org-capture) - - Files with the ‘.org’ extension use Org mode by default. To turn on -Org mode in a file that does not have the extension ‘.org’, make the -first line of a file look like this: - - MY PROJECTS -*- mode: org; -*- - -which selects Org mode for this buffer no matter what the file’s name -is. See also the variable ‘org-insert-mode-line-in-empty-file’. - - Many commands in Org work on the region if the region is _active_. -To make use of this, you need to have Transient Mark mode turned on, -which is the default. If you do not like it, you can create an active -region by using the mouse to select a region, or pressing ‘C-<SPC>’ -twice before moving point. - - ---------- Footnotes ---------- - - (1) If you do not use Font Lock globally turn it on in Org buffer -with ‘(add-hook 'org-mode-hook #'turn-on-font-lock)’. - - -File: org.info, Node: Feedback, Next: Conventions, Prev: Activation, Up: Introduction - -1.4 Feedback -============ - -If you find problems with Org, or if you have questions, remarks, or -ideas about it, please send an email to the Org mailing list -<emacs-orgmode@gnu.org>. You can subscribe to the list from this web -page (https://lists.gnu.org/mailman/listinfo/emacs-orgmode). If you are -not a member of the mailing list, your mail will be passed to the list -after a moderator has approved it(1). We ask you to read and respect -the GNU Kind Communications Guidelines -(https://www.gnu.org/philosophy/kind-communication.html) when sending -messages on this mailing list. - - For bug reports, please first try to reproduce the bug with the -latest version of Org available—if you are running an outdated version, -it is quite possible that the bug has been fixed already. If the bug -persists, prepare a report and provide as much information as possible, -including the version information of Emacs (‘M-x emacs-version’) and Org -(‘M-x org-version’), as well as the Org related setup in the Emacs init -file. The easiest way to do this is to use the command - - M-x org-submit-bug-report <RET> - -which puts all this information into an Emacs mail buffer so that you -only need to add your description. If you are not sending the Email -from within Emacs, please copy and paste the content into your Email -program. - - Sometimes you might face a problem due to an error in your Emacs or -Org mode setup. Before reporting a bug, it is very helpful to start -Emacs with minimal customizations and reproduce the problem. Doing so -often helps you determine if the problem is with your customization or -with Org mode itself. You can start a typical minimal session with a -command like the example below. - - $ emacs -Q -l /path/to/minimal-org.el - - However if you are using Org mode as distributed with Emacs, a -minimal setup is not necessary. In that case it is sufficient to start -Emacs as ‘emacs -Q’. The ‘minimal-org.el’ setup file can have contents -as shown below. - - ;;; Minimal setup to load latest `org-mode'. - - ;; Activate debugging. - (setq debug-on-error t - debug-on-signal nil - debug-on-quit nil) - - ;; Add latest Org mode to load path. - (add-to-list 'load-path (expand-file-name "/path/to/org-mode/lisp")) - - If an error occurs, a “backtrace” can be very useful—see below on how -to create one. Often a small example file helps, along with clear -information about: - - 1. What exactly did you do? - 2. What did you expect to happen? - 3. What happened instead? - - Thank you for helping to improve this program. - -How to create a useful backtrace --------------------------------- - -If working with Org produces an error with a message you do not -understand, you may have hit a bug. The best way to report this is by -providing, in addition to what was mentioned above, a backtrace. This -is information from the built-in debugger about where and how the error -occurred. Here is how to produce a useful backtrace: - - 1. Reload uncompiled versions of all Org mode Lisp files. The - backtrace contains much more information if it is produced with - uncompiled code. To do this, use - - C-u M-x org-reload <RET> - - or, from the menu: Org → Refresh/Reload → Reload Org uncompiled. - - 2. Then, activate the debugger: - - M-x toggle-debug-on-error <RET> - - or, from the menu: Options → Enter Debugger on Error. - - 3. Do whatever you have to do to hit the error. Do not forget to - document the steps you take. - - 4. When you hit the error, a ‘*Backtrace*’ buffer appears on the - screen. Save this buffer to a file—for example using ‘C-x C-w’—and - attach it to your bug report. - - ---------- Footnotes ---------- - - (1) Please consider subscribing to the mailing list in order to -minimize the work the mailing list moderators have to do. - - -File: org.info, Node: Conventions, Prev: Feedback, Up: Introduction - -1.5 Typesetting Conventions Used in this Manual -=============================================== - -TODO keywords, tags, properties, etc. -------------------------------------- - -Org uses various syntactical elements: TODO keywords, tags, property -names, keywords, blocks, etc. In this manual we use the following -conventions: - -‘TODO’ -‘WAITING’ - TODO keywords are written with all capitals, even if they are - user-defined. - -‘boss’ -‘ARCHIVE’ - Tags are case-sensitive. User-defined tags are usually written in - lowercase; built-in tags with special meaning are written as they - should appear in the document, usually with all capitals. - -‘Release’ -‘PRIORITY’ - User-defined properties are capitalized; built-in properties with - special meaning are written with all capitals. - -‘TITLE’ -‘BEGIN’ ... ‘END’ - Keywords and blocks are written in uppercase to enhance their - readability, but you can use lowercase in your Org files. - -Key bindings and commands -------------------------- - -The manual lists both the keys and the corresponding commands for -accessing a functionality. Org mode often uses the same key for -different functions, depending on context. The command that is bound to -such keys has a generic name, like ‘org-metaright’. In the manual we -will, wherever possible, give the function that is internally called by -the generic command. For example, in the chapter on document structure, -‘M-<RIGHT>’ will be listed to call ‘org-do-demote’, while in the chapter -on tables, it will be listed to call ‘org-table-move-column-right’. - - -File: org.info, Node: Document Structure, Next: Tables, Prev: Introduction, Up: Top - -2 Document Structure -******************** - -Org is an outliner. Outlines allow a document to be organized in a -hierarchical structure, which, least for me, is the best representation -of notes and thoughts. An overview of this structure is achieved by -folding, i.e., hiding large parts of the document to show only the -general document structure and the parts currently being worked on. Org -greatly simplifies the use of outlines by compressing the entire show -and hide functionalities into a single command, ‘org-cycle’, which is -bound to the ‘<TAB>’ key. - -* Menu: - -* Headlines:: How to typeset Org tree headlines. -* Visibility Cycling:: Show and hide, much simplified. -* Motion:: Jumping to other headlines. -* Structure Editing:: Changing sequence and level of headlines. -* Sparse Trees:: Matches embedded in context. -* Plain Lists:: Additional structure within an entry. -* Drawers:: Tucking stuff away. -* Blocks:: Folding blocks. - - -File: org.info, Node: Headlines, Next: Visibility Cycling, Up: Document Structure - -2.1 Headlines -============= - -Headlines define the structure of an outline tree. Org headlines start -on the left margin(1) with one or more stars followed by a space. For -example: - - * Top level headline - ** Second level - *** Third level - some text - *** Third level - more text - * Another top level headline - - The name defined in ‘org-footnote-section’ is reserved. Do not use -it as a title for your own headings. - - Some people find the many stars too noisy and would prefer an outline -that has whitespace followed by a single star as headline starters. -This can be achieved using a Org Indent minor mode. See *note Clean -View:: for more information. - - Headlines are not numbered. However, you may want to dynamically -number some, or all, of them. See *note Dynamic Headline Numbering::. - - An empty line after the end of a subtree is considered part of it and -is hidden when the subtree is folded. However, if you leave at least -two empty lines, one empty line remains visible after folding the -subtree, in order to structure the collapsed view. See the variable -‘org-cycle-separator-lines’ to modify this behavior. - - ---------- Footnotes ---------- - - (1) See the variables ‘org-special-ctrl-a/e’, ‘org-special-ctrl-k’, -and ‘org-ctrl-k-protect-subtree’ to configure special behavior of ‘C-a’, -‘C-e’, and ‘C-k’ in headlines. Note also that clocking only works with -headings indented less than 30 stars. - - -File: org.info, Node: Visibility Cycling, Next: Motion, Prev: Headlines, Up: Document Structure - -2.2 Visibility Cycling -====================== - -* Menu: - -* Global and local cycling:: Cycling through various visibility states. -* Initial visibility:: Setting the initial visibility state. -* Catching invisible edits:: Preventing mistakes when editing invisible parts. - - -File: org.info, Node: Global and local cycling, Next: Initial visibility, Up: Visibility Cycling - -2.2.1 Global and local cycling ------------------------------- - -Outlines make it possible to hide parts of the text in the buffer. Org -uses just two commands, bound to ‘<TAB>’ and ‘S-<TAB>’ to change the -visibility in the buffer. - -‘<TAB>’ (‘org-cycle’) - _Subtree cycling_: Rotate current subtree among the states - - ,-> FOLDED -> CHILDREN -> SUBTREE --. - '-----------------------------------' - - Point must be on a headline for this to work(1). - -‘S-<TAB>’ (‘org-global-cycle’) -‘C-u <TAB>’ - _Global cycling_: Rotate the entire buffer among the states - - ,-> OVERVIEW -> CONTENTS -> SHOW ALL --. - '--------------------------------------' - - When ‘S-<TAB>’ is called with a numeric prefix argument N, view - contents only up to headlines of level N. - - Note that inside tables (see *note Tables::), ‘S-<TAB>’ jumps to - the previous field instead. - - You can run global cycling using ‘<TAB>’ only if point is at the - very beginning of the buffer, but not on a headline, and - ‘org-cycle-global-at-bob’ is set to a non-‘nil’ value. - -‘C-u C-u <TAB>’ (‘org-set-startup-visibility’) - Switch back to the startup visibility of the buffer (see *note - Initial visibility::). - -‘C-u C-u C-u <TAB>’ (‘outline-show-all’) - Show all, including drawers. - -‘C-c C-r’ (‘org-reveal’) - Reveal context around point, showing the current entry, the - following heading and the hierarchy above. It is useful for - working near a location that has been exposed by a sparse tree - command (see *note Sparse Trees::) or an agenda command (see *note - Agenda Commands::). With a prefix argument, show, on each level, - all sibling headings. With a double prefix argument, also show the - entire subtree of the parent. - -‘C-c C-k’ (‘outline-show-branches’) - Expose all the headings of the subtree, but not their bodies. - -‘C-c <TAB>’ (‘outline-show-children’) - Expose all direct children of the subtree. With a numeric prefix - argument N, expose all children down to level N. - -‘C-c C-x b’ (‘org-tree-to-indirect-buffer’) - Show the current subtree in an indirect buffer(2). With a numeric - prefix argument N, go up to level N and then take that tree. If N - is negative then go up that many levels. With a ‘C-u’ prefix, do - not remove the previously used indirect buffer. - -‘C-c C-x v’ (‘org-copy-visible’) - Copy the _visible_ text in the region into the kill ring. - - ---------- Footnotes ---------- - - (1) See, however, the option ‘org-cycle-emulate-tab’. - - (2) The indirect buffer contains the entire buffer, but is narrowed -to the current tree. Editing the indirect buffer also changes the -original buffer, but without affecting visibility in that buffer. For -more information about indirect buffers, see *note GNU Emacs Manual: -(emacs)Indirect Buffers. - - -File: org.info, Node: Initial visibility, Next: Catching invisible edits, Prev: Global and local cycling, Up: Visibility Cycling - -2.2.2 Initial visibility ------------------------- - -When Emacs first visits an Org file, the global state is set to -‘showeverything’, i.e., all file content is visible(1). This can be -configured through the variable ‘org-startup-folded’, or on a per-file -basis by adding one of the following lines anywhere in the buffer: - - #+STARTUP: overview - #+STARTUP: content - #+STARTUP: showall - #+STARTUP: show2levels - #+STARTUP: show3levels - #+STARTUP: show4levels - #+STARTUP: show5levels - #+STARTUP: showeverything - - Furthermore, any entries with a ‘VISIBILITY’ property (see *note -Properties and Columns::) get their visibility adapted accordingly. -Allowed values for this property are ‘folded’, ‘children’, ‘content’, -and ‘all’. - -‘C-u C-u <TAB>’ (‘org-set-startup-visibility’) - Switch back to the startup visibility of the buffer, i.e., whatever - is requested by startup options and ‘VISIBILITY’ properties in - individual entries. - - ---------- Footnotes ---------- - - (1) When ‘org-agenda-inhibit-startup’ is non-‘nil’, Org does not -honor the default visibility state when first opening a file for the -agenda (see *note Speeding Up Your Agendas::). - - -File: org.info, Node: Catching invisible edits, Prev: Initial visibility, Up: Visibility Cycling - -2.2.3 Catching invisible edits ------------------------------- - -Sometimes you may inadvertently edit an invisible part of the buffer and -be confused on what has been edited and how to undo the mistake. -Setting ‘org-catch-invisible-edits’ to non-‘nil’ helps preventing this. -See the docstring of this option on how Org should catch invisible edits -and process them. - - -File: org.info, Node: Motion, Next: Structure Editing, Prev: Visibility Cycling, Up: Document Structure - -2.3 Motion -========== - -The following commands jump to other headlines in the buffer. - -‘C-c C-n’ (‘org-next-visible-heading’) - Next heading. - -‘C-c C-p’ (‘org-previous-visible-heading’) - Previous heading. - -‘C-c C-f’ (‘org-forward-heading-same-level’) - Next heading same level. - -‘C-c C-b’ (‘org-backward-heading-same-level’) - Previous heading same level. - -‘C-c C-u’ (‘outline-up-heading’) - Backward to higher level heading. - -‘C-c C-j’ (‘org-goto’) - Jump to a different place without changing the current outline - visibility. Shows the document structure in a temporary buffer, - where you can use the following keys to find your destination: - - ‘<TAB>’ Cycle visibility. - ‘<DOWN>’ / ‘<UP>’ Next/previous visible headline. - ‘<RET>’ Select this location. - ‘/’ Do a Sparse-tree search - - The following keys work if you turn off ‘org-goto-auto-isearch’ - - ‘n’ / ‘p’ Next/previous visible headline. - ‘f’ / ‘b’ Next/previous headline same level. - ‘u’ One level up. - ‘0’ ... ‘9’ Digit argument. - ‘q’ Quit. - - See also the variable ‘org-goto-interface’. - - -File: org.info, Node: Structure Editing, Next: Sparse Trees, Prev: Motion, Up: Document Structure - -2.4 Structure Editing -===================== - -‘M-<RET>’ (‘org-meta-return’) - Insert a new heading, item or row. - - If the command is used at the _beginning_ of a line, and if there - is a heading or a plain list item (see *note Plain Lists::) at - point, the new heading/item is created _before_ the current line. - When used at the beginning of a regular line of text, turn that - line into a heading. - - When this command is used in the middle of a line, the line is - split and the rest of the line becomes the new item or headline. - If you do not want the line to be split, customize - ‘org-M-RET-may-split-line’. - - Calling the command with a ‘C-u’ prefix unconditionally inserts a - new heading at the end of the current subtree, thus preserving its - contents. With a double ‘C-u C-u’ prefix, the new heading is - created at the end of the parent subtree instead. - -‘C-<RET>’ (‘org-insert-heading-respect-content’) - Insert a new heading at the end of the current subtree. - -‘M-S-<RET>’ (‘org-insert-todo-heading’) - Insert new TODO entry with same level as current heading. See also - the variable ‘org-treat-insert-todo-heading-as-state-change’. - -‘C-S-<RET>’ (‘org-insert-todo-heading-respect-content’) - Insert new TODO entry with same level as current heading. Like - ‘C-<RET>’, the new headline is inserted after the current subtree. - -‘<TAB>’ (‘org-cycle’) - In a new entry with no text yet, the first ‘<TAB>’ demotes the - entry to become a child of the previous one. The next ‘<TAB>’ - makes it a parent, and so on, all the way to top level. Yet - another ‘<TAB>’, and you are back to the initial level. - -‘M-<LEFT>’ (‘org-do-promote’) -‘M-<RIGHT>’ (‘org-do-demote’) - Promote or demote current heading by one level. - - When there is an active region—i.e., when Transient Mark mode is - active—promotion and demotion work on all headlines in the region. - To select a region of headlines, it is best to place both point and - mark at the beginning of a line, mark at the beginning of the first - headline, and point at the line just after the last headline to - change. - -‘M-S-<LEFT>’ (‘org-promote-subtree’) - Promote the current subtree by one level. - -‘M-S-<RIGHT>’ (‘org-demote-subtree’) - Demote the current subtree by one level. - -‘M-<UP>’ (‘org-move-subtree-up’) - Move subtree up, i.e., swap with previous subtree of same level. - -‘M-<DOWN>’ (‘org-move-subtree-down’) - Move subtree down, i.e., swap with next subtree of same level. - -‘C-c @’ (‘org-mark-subtree’) - Mark the subtree at point. Hitting repeatedly marks subsequent - subtrees of the same level as the marked subtree. - -‘C-c C-x C-w’ (‘org-cut-subtree’) - Kill subtree, i.e., remove it from buffer but save in kill ring. - With a numeric prefix argument N, kill N sequential subtrees. - -‘C-c C-x M-w’ (‘org-copy-subtree’) - Copy subtree to kill ring. With a numeric prefix argument N, copy - the N sequential subtrees. - -‘C-c C-x C-y’ (‘org-paste-subtree’) - Yank subtree from kill ring. This does modify the level of the - subtree to make sure the tree fits in nicely at the yank position. - The yank level can also be specified with a numeric prefix - argument, or by yanking after a headline marker like ‘****’. - -‘C-y’ (‘org-yank’) - Depending on the variables ‘org-yank-adjusted-subtrees’ and - ‘org-yank-folded-subtrees’, Org’s internal ‘yank’ command pastes - subtrees folded and in a clever way, using the same command as ‘C-c - C-x C-y’. With the default settings, no level adjustment takes - place, but the yanked tree is folded unless doing so would swallow - text previously visible. Any prefix argument to this command - forces a normal ‘yank’ to be executed, with the prefix passed - along. A good way to force a normal yank is ‘C-u C-y’. If you use - ‘yank-pop’ after a yank, it yanks previous kill items plainly, - without adjustment and folding. - -‘C-c C-x c’ (‘org-clone-subtree-with-time-shift’) - Clone a subtree by making a number of sibling copies of it. You - are prompted for the number of copies to make, and you can also - specify if any timestamps in the entry should be shifted. This can - be useful, for example, to create a number of tasks related to a - series of lectures to prepare. For more details, see the docstring - of the command ‘org-clone-subtree-with-time-shift’. - -‘C-c C-w’ (‘org-refile’) - Refile entry or region to a different location. See *note Refile - and Copy::. - -‘C-c ^’ (‘org-sort’) - Sort same-level entries. When there is an active region, all - entries in the region are sorted. Otherwise the children of the - current headline are sorted. The command prompts for the sorting - method, which can be alphabetically, numerically, by time—first - timestamp with active preferred, creation time, scheduled time, - deadline time—by priority, by TODO keyword—in the sequence the - keywords have been defined in the setup—or by the value of a - property. Reverse sorting is possible as well. You can also - supply your own function to extract the sorting key. With a ‘C-u’ - prefix, sorting is case-sensitive. - -‘C-x n s’ (‘org-narrow-to-subtree’) - Narrow buffer to current subtree. - -‘C-x n b’ (‘org-narrow-to-block’) - Narrow buffer to current block. - -‘C-x n w’ (‘widen’) - Widen buffer to remove narrowing. - -‘C-c *’ (‘org-toggle-heading’) - Turn a normal line or plain list item into a headline—so that it - becomes a subheading at its location. Also turn a headline into a - normal line by removing the stars. If there is an active region, - turn all lines in the region into headlines. If the first line in - the region was an item, turn only the item lines into headlines. - Finally, if the first line is a headline, remove the stars from all - headlines in the region. - - Note that when point is inside a table (see *note Tables::), the -Meta-Cursor keys have different functionality. - - -File: org.info, Node: Sparse Trees, Next: Plain Lists, Prev: Structure Editing, Up: Document Structure - -2.5 Sparse Trees -================ - -An important feature of Org mode is the ability to construct _sparse -trees_ for selected information in an outline tree, so that the entire -document is folded as much as possible, but the selected information is -made visible along with the headline structure above it(1). Just try it -out and you will see immediately how it works. - - Org mode contains several commands creating such trees, all these -commands can be accessed through a dispatcher: - -‘C-c /’ (‘org-sparse-tree’) - This prompts for an extra key to select a sparse-tree creating - command. - -‘C-c / r’ or ‘C-c / /’ (‘org-occur’) - Prompts for a regexp (see *note Regular Expressions::) and shows a - sparse tree with all matches. If the match is in a headline, the - headline is made visible. If the match is in the body of an entry, - headline and body are made visible. In order to provide minimal - context, also the full hierarchy of headlines above the match is - shown, as well as the headline following the match. Each match is - also highlighted; the highlights disappear when the buffer is - changed by an editing command, or by pressing ‘C-c C-c’(2). When - called with a ‘C-u’ prefix argument, previous highlights are kept, - so several calls to this command can be stacked. - -‘M-g n’ or ‘M-g M-n’ (‘next-error’) - Jump to the next sparse tree match in this buffer. - -‘M-g p’ or ‘M-g M-p’ (‘previous-error’) - Jump to the previous sparse tree match in this buffer. - - For frequently used sparse trees of specific search strings, you can -use the variable ‘org-agenda-custom-commands’ to define fast keyboard -access to specific sparse trees. These commands will then be accessible -through the agenda dispatcher (see *note Agenda Dispatcher::). For -example: - - (setq org-agenda-custom-commands - '(("f" occur-tree "FIXME"))) - -defines the key ‘f’ as a shortcut for creating a sparse tree matching -the string ‘FIXME’. - - The other sparse tree commands select headings based on TODO -keywords, tags, or properties and are discussed later in this manual. - - To print a sparse tree, you can use the Emacs command -‘ps-print-buffer-with-faces’ which does not print invisible parts of the -document. Or you can use the command ‘C-c C-e C-v’ to export only the -visible part of the document and print the resulting file. - - ---------- Footnotes ---------- - - (1) See also the variable ‘org-show-context-detail’ to decide how -much context is shown around each match. - - (2) This depends on the option ‘org-remove-highlights-with-change’. - - -File: org.info, Node: Plain Lists, Next: Drawers, Prev: Sparse Trees, Up: Document Structure - -2.6 Plain Lists -=============== - -Within an entry of the outline tree, hand-formatted lists can provide -additional structure. They also provide a way to create lists of -checkboxes (see *note Checkboxes::). Org supports editing such lists, -and every exporter (see *note Exporting::) can parse and format them. - - Org knows ordered lists, unordered lists, and description lists. - - • _Unordered_ list items start with ‘-’, ‘+’, or ‘*’(1) as bullets. - - • _Ordered_ list items start with a numeral followed by either a - period or a right parenthesis(2), such as ‘1.’ or ‘1)’(3) If you - want a list to start with a different value—e.g., 20—start the text - of the item with ‘[@20]’(4). Those constructs can be used in any - item of the list in order to enforce a particular numbering. - - • _Description_ list items are unordered list items, and contain the - separator ‘::’ to distinguish the description _term_ from the - description. - - Items belonging to the same list must have the same indentation on -the first line. In particular, if an ordered list reaches number ‘10.’, -then the 2-digit numbers must be written left-aligned with the other -numbers in the list. An item ends before the next line that is less or -equally indented than its bullet/number. - - A list ends whenever every item has ended, which means before any -line less or equally indented than items at top level. It also ends -before two blank lines. In that case, all items are closed. Here is an -example: - - * Lord of the Rings - My favorite scenes are (in this order) - 1. The attack of the Rohirrim - 2. Eowyn's fight with the witch king - + this was already my favorite scene in the book - + I really like Miranda Otto. - 3. Peter Jackson being shot by Legolas - - on DVD only - He makes a really funny face when it happens. - But in the end, no individual scenes matter but the film as a whole. - Important actors in this film are: - - Elijah Wood :: He plays Frodo - - Sean Astin :: He plays Sam, Frodo's friend. I still remember him - very well from his role as Mikey Walsh in /The Goonies/. - - Org supports these lists by tuning filling and wrapping commands to -deal with them correctly, and by exporting them properly (see *note -Exporting::). Since indentation is what governs the structure of these -lists, many structural constructs like ‘#+BEGIN_’ blocks can be indented -to signal that they belong to a particular item. - - If you find that using a different bullet for a sub-list—than that -used for the current list-level—improves readability, customize the -variable ‘org-list-demote-modify-bullet’. To get a greater difference -of indentation between items and theirs sub-items, customize -‘org-list-indent-offset’. - - The following commands act on items when point is in the first line -of an item—the line with the bullet or number. Some of them imply the -application of automatic rules to keep list structure intact. If some -of these actions get in your way, configure ‘org-list-automatic-rules’ -to disable them individually. - -‘<TAB>’ (‘org-cycle’) - Items can be folded just like headline levels. Normally this works - only if point is on a plain list item. For more details, see the - variable ‘org-cycle-include-plain-lists’. If this variable is set - to ‘integrate’, plain list items are treated like low-level - headlines. The level of an item is then given by the indentation - of the bullet/number. Items are always subordinate to real - headlines, however; the hierarchies remain completely separated. - In a new item with no text yet, the first ‘<TAB>’ demotes the item - to become a child of the previous one. Subsequent ‘<TAB>’s move - the item to meaningful levels in the list and eventually get it - back to its initial position. - -‘M-<RET>’ (‘org-insert-heading’) - Insert new item at current level. With a prefix argument, force a - new heading (see *note Structure Editing::). If this command is - used in the middle of an item, that item is _split_ in two, and the - second part becomes the new item(5). If this command is executed - _before item’s body_, the new item is created _before_ the current - one. - -‘M-S-<RET>’ - Insert a new item with a checkbox (see *note Checkboxes::). - -‘S-<UP>’ -‘S-<DOWN>’ - Jump to the previous/next item in the current list, but only if - ‘org-support-shift-select’ is off(6). If not, you can still use - paragraph jumping commands like ‘C-<UP>’ and ‘C-<DOWN>’ to quite - similar effect. - -‘M-<UP>’ -‘M-<DOWN>’ - Move the item including subitems up/down(7), i.e., swap with - previous/next item of same indentation. If the list is ordered, - renumbering is automatic. - -‘M-<LEFT>’ -‘M-<RIGHT>’ - Decrease/increase the indentation of an item, leaving children - alone. - -‘M-S-<LEFT>’ -‘M-S-<RIGHT>’ - Decrease/increase the indentation of the item, including subitems. - Initially, the item tree is selected based on current indentation. - When these commands are executed several times in direct - succession, the initially selected region is used, even if the new - indentation would imply a different hierarchy. To use the new - hierarchy, break the command chain by moving point. - - As a special case, using this command on the very first item of a - list moves the whole list. This behavior can be disabled by - configuring ‘org-list-automatic-rules’. The global indentation of - a list has no influence on the text _after_ the list. - -‘C-c C-c’ - If there is a checkbox (see *note Checkboxes::) in the item line, - toggle the state of the checkbox. In any case, verify bullets and - indentation consistency in the whole list. - -‘C-c -’ - Cycle the entire list level through the different itemize/enumerate - bullets (‘-’, ‘+’, ‘*’, ‘1.’, ‘1)’) or a subset of them, depending - on ‘org-plain-list-ordered-item-terminator’, the type of list, and - its indentation. With a numeric prefix argument N, select the Nth - bullet from this list. If there is an active region when calling - this, all lines are converted to list items. With a prefix - argument, the selected text is changed into a single item. If the - first line already was a list item, any item marker is removed from - the list. Finally, even without an active region, a normal line is - converted into a list item. - -‘C-c *’ - Turn a plain list item into a headline—so that it becomes a - subheading at its location. See *note Structure Editing::, for a - detailed explanation. - -‘C-c C-*’ - Turn the whole plain list into a subtree of the current heading. - Checkboxes (see *note Checkboxes::) become ‘TODO’, respectively - ‘DONE’, keywords when unchecked, respectively checked. - -‘S-<LEFT>’ -‘S-<RIGHT>’ - This command also cycles bullet styles when point is in on the - bullet or anywhere in an item line, details depending on - ‘org-support-shift-select’. - -‘C-c ^’ - Sort the plain list. Prompt for the sorting method: numerically, - alphabetically, by time, or by custom function. - - ---------- Footnotes ---------- - - (1) When using ‘*’ as a bullet, lines must be indented so that they -are not interpreted as headlines. Also, when you are hiding leading -stars to get a clean outline view, plain list items starting with a star -may be hard to distinguish from true headlines. In short: even though -‘*’ is supported, it may be better to not use it for plain list items. - - (2) You can filter out any of them by configuring -‘org-plain-list-ordered-item-terminator’. - - (3) You can also get ‘a.’, ‘A.’, ‘a)’ and ‘A)’ by configuring -‘org-list-allow-alphabetical’. To minimize confusion with normal text, -those are limited to one character only. Beyond that limit, bullets -automatically become numbers. - - (4) If there’s a checkbox in the item, the cookie must be put -_before_ the checkbox. If you have activated alphabetical lists, you -can also use counters like ‘[@b]’. - - (5) If you do not want the item to be split, customize the variable -‘org-M-RET-may-split-line’. - - (6) If you want to cycle around items that way, you may customize -‘org-list-use-circular-motion’. - - (7) See ‘org-list-use-circular-motion’ for a cyclic behavior. - - -File: org.info, Node: Drawers, Next: Blocks, Prev: Plain Lists, Up: Document Structure - -2.7 Drawers -=========== - -Sometimes you want to keep information associated with an entry, but you -normally do not want to see it. For this, Org mode has _drawers_. They -can contain anything but a headline and another drawer. Drawers look -like this: - - ** This is a headline - Still outside the drawer - :DRAWERNAME: - This is inside the drawer. - :END: - After the drawer. - - You can interactively insert a drawer at point by calling -‘org-insert-drawer’, which is bound to ‘C-c C-x d’. With an active -region, this command puts the region inside the drawer. With a prefix -argument, this command calls ‘org-insert-property-drawer’, which creates -a ‘PROPERTIES’ drawer right below the current headline. Org mode uses -this special drawer for storing properties (see *note Properties and -Columns::). You cannot use it for anything else. - - Completion over drawer keywords is also possible using ‘M-<TAB>’(1). - - Visibility cycling (see *note Visibility Cycling::) on the headline -hides and shows the entry, but keep the drawer collapsed to a single -line. In order to look inside the drawer, you need to move point to the -drawer line and press ‘<TAB>’ there. - - You can also arrange for state change notes (see *note Tracking TODO -state changes::) and clock times (see *note Clocking Work Time::) to be -stored in a ‘LOGBOOK’ drawer. If you want to store a quick note there, -in a similar way to state changes, use - -‘C-c C-z’ - Add a time-stamped note to the ‘LOGBOOK’ drawer. - - ---------- Footnotes ---------- - - (1) Many desktops intercept ‘M-<TAB>’ to switch windows. Use ‘C-M-i’ -or ‘<ESC> <TAB>’ instead. - - -File: org.info, Node: Blocks, Prev: Drawers, Up: Document Structure - -2.8 Blocks -========== - -Org mode uses ‘#+BEGIN’ ... ‘#+END’ blocks for various purposes from -including source code examples (see *note Literal Examples::) to -capturing time logging information (see *note Clocking Work Time::). -These blocks can be folded and unfolded by pressing ‘<TAB>’ in the -‘#+BEGIN’ line. You can also get all blocks folded at startup by -configuring the variable ‘org-hide-block-startup’ or on a per-file basis -by using - - #+STARTUP: hideblocks - #+STARTUP: nohideblocks - - -File: org.info, Node: Tables, Next: Hyperlinks, Prev: Document Structure, Up: Top - -3 Tables -******** - -Org comes with a fast and intuitive table editor. Spreadsheet-like -calculations are supported using the Emacs Calc package (see *note GNU -Emacs Calculator Manual: (calc)Top.). - -* Menu: - -* Built-in Table Editor:: Simple tables. -* Column Width and Alignment:: Overrule the automatic settings. -* Column Groups:: Grouping to trigger vertical lines. -* Orgtbl Mode:: The table editor as minor mode. -* The Spreadsheet:: The table editor has spreadsheet capabilities. -* Org Plot:: Plotting from Org tables. - - -File: org.info, Node: Built-in Table Editor, Next: Column Width and Alignment, Up: Tables - -3.1 Built-in Table Editor -========================= - -Org makes it easy to format tables in plain ASCII. Any line with ‘|’ as -the first non-whitespace character is considered part of a table. ‘|’ -is also the column separator(1). Moreover, a line starting with ‘|-’ is -a horizontal rule. It separates rows explicitly. Rows before the first -horizontal rule are header lines. A table might look like this: - - | Name | Phone | Age | - |-------+-------+-----| - | Peter | 1234 | 17 | - | Anna | 4321 | 25 | - - A table is re-aligned automatically each time you press ‘<TAB>’, -‘<RET>’ or ‘C-c C-c’ inside the table. ‘<TAB>’ also moves to the next -field—‘<RET>’ to the next row—and creates new table rows at the end of -the table or before horizontal lines. The indentation of the table is -set by the first line. Horizontal rules are automatically expanded on -every re-align to span the whole table width. So, to create the above -table, you would only type - - |Name|Phone|Age| - |- - -and then press ‘<TAB>’ to align the table and start filling in fields. -Even faster would be to type ‘|Name|Phone|Age’ followed by ‘C-c <RET>’. - - When typing text into a field, Org treats ‘DEL’, ‘Backspace’, and all -character keys in a special way, so that inserting and deleting avoids -shifting other fields. Also, when typing _immediately_ after point was -moved into a new field with ‘<TAB>’, ‘S-<TAB>’ or ‘<RET>’, the field is -automatically made blank. If this behavior is too unpredictable for -you, configure the option ‘org-table-auto-blank-field’. - -Creation and conversion ------------------------ - -‘C-c |’ (‘org-table-create-or-convert-from-region’) - Convert the active region to table. If every line contains at - least one ‘<TAB>’ character, the function assumes that the material - is tab separated. If every line contains a comma, comma-separated - values (CSV) are assumed. If not, lines are split at whitespace - into fields. You can use a prefix argument to force a specific - separator: ‘C-u’ forces CSV, ‘C-u C-u’ forces ‘<TAB>’, ‘C-u C-u - C-u’ prompts for a regular expression to match the separator, and a - numeric argument N indicates that at least N consecutive spaces, or - alternatively a ‘<TAB>’ will be the separator. - - If there is no active region, this command creates an empty Org - table. But it is easier just to start typing, like ‘| N a m e | P - h o n e | A g e <RET> | - <TAB>’. - -Re-aligning and field motion ----------------------------- - -‘C-c C-c’ (‘org-table-align’) - Re-align the table without moving point. - -‘<TAB>’ (‘org-table-next-field’) - Re-align the table, move to the next field. Creates a new row if - necessary. - -‘M-x org-table-blank-field’ - Blank the field at point. - -‘S-<TAB>’ (‘org-table-previous-field’) - Re-align, move to previous field. - -‘<RET>’ (‘org-table-next-row’) - Re-align the table and move down to next row. Creates a new row if - necessary. At the beginning or end of a line, ‘<RET>’ still - inserts a new line, so it can be used to split a table. - -‘M-a’ (‘org-table-beginning-of-field’) - Move to beginning of the current table field, or on to the previous - field. - -‘M-e’ (‘org-table-end-of-field’) - Move to end of the current table field, or on to the next field. - -Column and row editing ----------------------- - -‘M-<LEFT>’ (‘org-table-move-column-left’) - Move the current column left. - -‘M-<RIGHT>’ (‘org-table-move-column-right’) - Move the current column right. - -‘M-S-<LEFT>’ (‘org-table-delete-column’) - Kill the current column. - -‘M-S-<RIGHT>’ (‘org-table-insert-column’) - Insert a new column at point position. Move the recent column and - all cells to the right of this column to the right. - -‘M-<UP>’ (‘org-table-move-row-up’) - Move the current row up. - -‘M-<DOWN>’ (‘org-table-move-row-down’) - Move the current row down. - -‘M-S-<UP>’ (‘org-table-kill-row’) - Kill the current row or horizontal line. - -‘S-<UP>’ (‘org-table-move-cell-up’) - Move cell up by swapping with adjacent cell. - -‘S-<DOWN>’ (‘org-table-move-cell-down’) - Move cell down by swapping with adjacent cell. - -‘S-<LEFT>’ (‘org-table-move-cell-left’) - Move cell left by swapping with adjacent cell. - -‘S-<RIGHT>’ (‘org-table-move-cell-right’) - Move cell right by swapping with adjacent cell. - -‘M-S-<DOWN>’ (‘org-table-insert-row’) - Insert a new row above the current row. With a prefix argument, - the line is created below the current one. - -‘C-c -’ (‘org-table-insert-hline’) - Insert a horizontal line below current row. With a prefix - argument, the line is created above the current line. - -‘C-c <RET>’ (‘org-table-hline-and-move’) - Insert a horizontal line below current row, and move point into the - row below that line. - -‘C-c ^’ (‘org-table-sort-lines’) - Sort the table lines in the region. The position of point - indicates the column to be used for sorting, and the range of lines - is the range between the nearest horizontal separator lines, or the - entire table. If point is before the first column, you are - prompted for the sorting column. If there is an active region, the - mark specifies the first line and the sorting column, while point - should be in the last line to be included into the sorting. The - command prompts for the sorting type, alphabetically, numerically, - or by time. You can sort in normal or reverse order. You can also - supply your own key extraction and comparison functions. When - called with a prefix argument, alphabetic sorting is - case-sensitive. - -Regions -------- - -‘C-c C-x M-w’ (‘org-table-copy-region’) - Copy a rectangular region from a table to a special clipboard. - Point and mark determine edge fields of the rectangle. If there is - no active region, copy just the current field. The process ignores - horizontal separator lines. - -‘C-c C-x C-w’ (‘org-table-cut-region’) - Copy a rectangular region from a table to a special clipboard, and - blank all fields in the rectangle. So this is the “cut” operation. - -‘C-c C-x C-y’ (‘org-table-paste-rectangle’) - Paste a rectangular region into a table. The upper left corner - ends up in the current field. All involved fields are overwritten. - If the rectangle does not fit into the present table, the table is - enlarged as needed. The process ignores horizontal separator - lines. - -‘M-<RET>’ (‘org-table-wrap-region’) - Split the current field at point position and move the rest to the - line below. If there is an active region, and both point and mark - are in the same column, the text in the column is wrapped to - minimum width for the given number of lines. A numeric prefix - argument may be used to change the number of desired lines. If - there is no region, but you specify a prefix argument, the current - field is made blank, and the content is appended to the field - above. - -Calculations ------------- - -‘C-c +’ (‘org-table-sum’) - Sum the numbers in the current column, or in the rectangle defined - by the active region. The result is shown in the echo area and can - be inserted with ‘C-y’. - -‘S-<RET>’ (‘org-table-copy-down’) - When current field is empty, copy from first non-empty field above. - When not empty, copy current field down to next row and move point - along with it. - - Depending on the variable ‘org-table-copy-increment’, integer and - time stamp field values, and fields prefixed or suffixed with a - whole number, can be incremented during copy. Also, a ‘0’ prefix - argument temporarily disables the increment. - - This key is also used by shift-selection and related modes (see - *note Conflicts::). - -Miscellaneous -------------- - -‘C-c `’ (‘org-table-edit-field’) - Edit the current field in a separate window. This is useful for - fields that are not fully visible (see *note Column Width and - Alignment::). When called with a ‘C-u’ prefix, just make the full - field visible, so that it can be edited in place. When called with - two ‘C-u’ prefixes, make the editor window follow point through the - table and always show the current field. The follow mode exits - automatically when point leaves the table, or when you repeat this - command with ‘C-u C-u C-c `’. - -‘M-x org-table-import’ - Import a file as a table. The table should be TAB or whitespace - separated. Use, for example, to import a spreadsheet table or data - from a database, because these programs generally can write - TAB-separated text files. This command works by inserting the file - into the buffer and then converting the region to a table. Any - prefix argument is passed on to the converter, which uses it to - determine the separator. - -‘C-c |’ (‘org-table-create-or-convert-from-region’) - Tables can also be imported by pasting tabular text into the Org - buffer, selecting the pasted text with ‘C-x C-x’ and then using the - ‘C-c |’ command (see *note Creation and conversion::). - -‘M-x org-table-export’ - Export the table, by default as a TAB-separated file. Use for data - exchange with, for example, spreadsheet or database programs. The - format used to export the file can be configured in the variable - ‘org-table-export-default-format’. You may also use properties - ‘TABLE_EXPORT_FILE’ and ‘TABLE_EXPORT_FORMAT’ to specify the file - name and the format for table export in a subtree. Org supports - quite general formats for exported tables. The exporter format is - the same as the format used by Orgtbl radio tables, see *note - Translator functions::, for a detailed description. - -‘M-x org-table-header-line-mode’ - Turn on the display of the first data row of the table at point in - the window header line when this first row is not visible anymore - in the buffer. You can activate this minor mode by default by - setting the option ‘org-table-header-line-p’ to ‘t’. - -‘M-x org-table-transpose-table-at-point’ - Transpose the table at point and eliminate hlines. - - ---------- Footnotes ---------- - - (1) To insert a vertical bar into a table field, use ‘\vert’ or, -inside a word ‘abc\vert{}def’. - - -File: org.info, Node: Column Width and Alignment, Next: Column Groups, Prev: Built-in Table Editor, Up: Tables - -3.2 Column Width and Alignment -============================== - -The width of columns is automatically determined by the table editor. -The alignment of a column is determined automatically from the fraction -of number-like versus non-number fields in the column. - - Editing a field may modify alignment of the table. Moving a -contiguous row or column—i.e., using ‘<TAB>’ or ‘<RET>’—automatically -re-aligns it. If you want to disable this behavior, set -‘org-table-automatic-realign’ to ‘nil’. In any case, you can always -align manually a table: - -‘C-c C-c’ (‘org-table-align’) - Align the current table. - - Setting the option ‘org-startup-align-all-tables’ re-aligns all -tables in a file upon visiting it. You can also set this option on a -per-file basis with: - - #+STARTUP: align - #+STARTUP: noalign - - Sometimes a single field or a few fields need to carry more text, -leading to inconveniently wide columns. Maybe you want to hide away -several columns or display them with a fixed width, regardless of -content, as shown in the following example. - - |---+---------------------+--------| |---+-------…+…| - | | <6> | | | | <6> …|…| - | 1 | one | some | ----\ | 1 | one …|…| - | 2 | two | boring | ----/ | 2 | two …|…| - | 3 | This is a long text | column | | 3 | This i…|…| - |---+---------------------+--------| |---+-------…+…| - - To set the width of a column, one field anywhere in the column may -contain just the string ‘<N>’ where N specifies the width as a number of -characters. You control displayed width of columns with the following -tools: - -‘C-c <TAB>’ (‘org-table-toggle-column-width’) - Shrink or expand current column. - - If a width cookie specifies a width W for the column, shrinking it - displays the first W visible characters only. Otherwise, the - column is shrunk to a single character. - - When called before the first column or after the last one, ask for - a list of column ranges to operate on. - -‘C-u C-c <TAB>’ (‘org-table-shrink’) - Shrink all columns with a column width. Expand the others. - -‘C-u C-u C-c <TAB>’ (‘org-table-expand’) - Expand all columns. - - To see the full text of a shrunk field, hold the mouse over it: a -tool-tip window then shows the full contents of the field. -Alternatively, ‘C-h .’ (‘display-local-help’) reveals them, too. For -convenience, any change near the shrunk part of a column expands it. - - Setting the option ‘org-startup-shrink-all-tables’ shrinks all -columns containing a width cookie in a file the moment it is visited. -You can also set this option on a per-file basis with: - - #+STARTUP: shrink - - If you would like to overrule the automatic alignment of number-rich -columns to the right and of string-rich columns to the left, you can use -‘<r>’, ‘<c>’ or ‘<l>’ in a similar fashion. You may also combine -alignment and field width like this: ‘<r10>’. - - Lines which only contain these formatting cookies are removed -automatically upon exporting the document. - - -File: org.info, Node: Column Groups, Next: Orgtbl Mode, Prev: Column Width and Alignment, Up: Tables - -3.3 Column Groups -================= - -When Org exports tables, it does so by default without vertical lines -because that is visually more satisfying in general. Occasionally -however, vertical lines can be useful to structure a table into groups -of columns, much like horizontal lines can do for groups of rows. In -order to specify column groups, you can use a special row where the -first field contains only ‘/’. The further fields can either contain -‘<’ to indicate that this column should start a group, ‘>’ to indicate -the end of a column, or ‘<>’ (no space between ‘<’ and ‘>’) to make a -column a group of its own. Upon export, boundaries between column -groups are marked with vertical lines. Here is an example: - - | N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) | - |---+-----+-----+-----+---------+------------| - | / | < | | > | < | > | - | 1 | 1 | 1 | 1 | 1 | 1 | - | 2 | 4 | 8 | 16 | 1.4142 | 1.1892 | - | 3 | 9 | 27 | 81 | 1.7321 | 1.3161 | - |---+-----+-----+-----+---------+------------| - #+TBLFM: $2=$1^2::$3=$1^3::$4=$1^4::$5=sqrt($1)::$6=sqrt(sqrt(($1))) - - It is also sufficient to just insert the column group starters after -every vertical line you would like to have: - - | N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) | - |---+-----+-----+-----+---------+------------| - | / | < | | | < | | - - -File: org.info, Node: Orgtbl Mode, Next: The Spreadsheet, Prev: Column Groups, Up: Tables - -3.4 The Orgtbl Minor Mode -========================= - -If you like the intuitive way the Org table editor works, you might also -want to use it in other modes like Text mode or Mail mode. The minor -mode Orgtbl mode makes this possible. You can always toggle the mode -with ‘M-x orgtbl-mode’. To turn it on by default, for example in -Message mode, use - - (add-hook 'message-mode-hook #'turn-on-orgtbl) - - Furthermore, with some special setup, it is possible to maintain -tables in arbitrary syntax with Orgtbl mode. For example, it is -possible to construct LaTeX tables with the underlying ease and power of -Orgtbl mode, including spreadsheet capabilities. For details, see *note -Tables in Arbitrary Syntax::. - - -File: org.info, Node: The Spreadsheet, Next: Org Plot, Prev: Orgtbl Mode, Up: Tables - -3.5 The Spreadsheet -=================== - -The table editor makes use of the Emacs Calc package to implement -spreadsheet-like capabilities. It can also evaluate Emacs Lisp forms to -derive fields from other fields. While fully featured, Org’s -implementation is not identical to other spreadsheets. For example, Org -knows the concept of a _column formula_ that will be applied to all -non-header fields in a column without having to copy the formula to each -relevant field. There is also a formula debugger, and a formula editor -with features for highlighting fields in the table corresponding to the -references at point in the formula, moving these references by arrow -keys. - -* Menu: - -* References:: How to refer to another field or range. -* Formula syntax for Calc:: Using Calc to compute stuff. -* Formula syntax for Lisp:: Writing formulas in Emacs Lisp. -* Durations and time values:: How to compute durations and time values. -* Field and range formulas:: Formula for specific (ranges of) fields. -* Column formulas:: Formulas valid for an entire column. -* Lookup functions:: Lookup functions for searching tables. -* Editing and debugging formulas:: Fixing formulas. -* Updating the table:: Recomputing all dependent fields. -* Advanced features:: Field and column names, automatic recalculation... - - -File: org.info, Node: References, Next: Formula syntax for Calc, Up: The Spreadsheet - -3.5.1 References ----------------- - -To compute fields in the table from other fields, formulas must -reference other fields or ranges. In Org, fields can be referenced by -name, by absolute coordinates, and by relative coordinates. To find out -what the coordinates of a field are, press ‘C-c ?’ in that field, or -press ‘C-c }’ to toggle the display of a grid. - -Field references -................ - -Formulas can reference the value of another field in two ways. Like in -any other spreadsheet, you may reference fields with a letter/number -combination like ‘B3’, meaning the second field in the third row. -However, Org prefers to use another, more general representation that -looks like this:(1) - - @ROW$COLUMN - - Column specifications can be absolute like ‘$1’, ‘$2’, ..., ‘$N’, or -relative to the current column, i.e., the column of the field which is -being computed, like ‘$+1’ or ‘$-2’. ‘$<’ and ‘$>’ are immutable -references to the first and last column, respectively, and you can use -‘$>>>’ to indicate the third column from the right. - - The row specification only counts data lines and ignores horizontal -separator lines, or “hlines”. Like with columns, you can use absolute -row numbers ‘@1’, ‘@2’, ..., ‘@N’, and row numbers relative to the -current row like ‘@+3’ or ‘@-1’. ‘@<’ and ‘@>’ are immutable references -the first and last row in the table, respectively. You may also specify -the row relative to one of the hlines: ‘@I’ refers to the first hline, -‘@II’ to the second, etc. ‘@-I’ refers to the first such line above the -current line, ‘@+I’ to the first such line below the current line. You -can also write ‘@III+2’ which is the second data line after the third -hline in the table. - - ‘@0’ and ‘$0’ refer to the current row and column, respectively, -i.e., to the row/column for the field being computed. Also, if you omit -either the column or the row part of the reference, the current -row/column is implied. - - Org’s references with _unsigned_ numbers are fixed references in the -sense that if you use the same reference in the formula for two -different fields, the same field is referenced each time. Org’s -references with _signed_ numbers are floating references because the -same reference operator can reference different fields depending on the -field being calculated by the formula. - - Here are a few examples: - -‘@2$3’ 2nd row, 3rd column (same as ‘C2’) -‘$5’ column 5 in the current row (same as ‘E&’) -‘@2’ current column, row 2 -‘@-1$-3’ field one row up, three columns to the left -‘@-I$2’ field just under hline above current row, column 2 -‘@>$5’ field in the last row, in column 5 - -Range references -................ - -You may reference a rectangular range of fields by specifying two field -references connected by two dots ‘..’. The ends are included in the -range. If both fields are in the current row, you may simply use -‘$2..$7’, but if at least one field is in a different row, you need to -use the general ‘@ROW$COLUMN’ format at least for the first field, i.e., -the reference must start with ‘@’ in order to be interpreted correctly. -Examples: - -‘$1..$3’ first three fields in the current row -‘$P..$Q’ range, using column names (see - *note Advanced features::) -‘$<<<..$>>’ start in third column, continue to the last but one -‘@2$1..@4$3’ nine fields between these two fields (same as ‘A2..C4’) -‘@-1$-2..@-1’ 3 fields in the row above, starting from 2 columns on - the left -‘@I..II’ between first and second hline, short for ‘@I..@II’ - -Range references return a vector of values that can be fed into Calc -vector functions. Empty fields in ranges are normally suppressed, so -that the vector contains only the non-empty fields. For other options -with the mode switches ‘E’, ‘N’ and examples, see *note Formula syntax -for Calc::. - -Field coordinates in formulas -............................. - -One of the very first actions during evaluation of Calc formulas and -Lisp formulas is to substitute ‘@#’ and ‘$#’ in the formula with the row -or column number of the field where the current result will go to. The -traditional Lisp formula equivalents are ‘org-table-current-dline’ and -‘org-table-current-column’. Examples: - -‘if(@# % 2, $#, string(""))’ - Insert column number on odd rows, set field to empty on even rows. - -‘$2 = '(identity remote(FOO, @@#$1))’ - Copy text or values of each row of column 1 of the table named FOO - into column 2 of the current table. - -‘@3 = 2 * remote(FOO, @1$$#)’ - Insert the doubled value of each column of row 1 of the table named - FOO into row 3 of the current table. - -For the second and third examples, table FOO must have at least as many -rows or columns as the current table. Note that this is inefficient(2) -for large number of rows. - -Named references -................ - -‘$name’ is interpreted as the name of a column, parameter or constant. -Constants are defined globally through the variable -‘org-table-formula-constants’, and locally—for the file—through a line -like this example: - - #+CONSTANTS: c=299792458. pi=3.14 eps=2.4e-6 - - Also, properties (see *note Properties and Columns::) can be used as -constants in table formulas: for a property ‘Xyz’ use the name -‘$PROP_Xyz’, and the property will be searched in the current outline -entry and in the hierarchy above it. If you have the ‘constants.el’ -package, it will also be used to resolve constants, including natural -constants like ‘$h’ for Planck’s constant, and units like ‘$km’ for -kilometers(3). Column names and parameters can be specified in special -table lines. These are described below, see *note Advanced features::. -All names must start with a letter, and further consist of letters and -numbers. - -Remote references -................. - -You may also reference constants, fields and ranges from a different -table, either in the current file or even in a different file. The -syntax is - - remote(NAME,REF) - -where NAME can be the name of a table in the current file as set by a -‘#+NAME:’ line before the table. It can also be the ID of an entry, -even in a different file, and the reference then refers to the first -table in that entry. REF is an absolute field or range reference as -described above for example ‘@3$3’ or ‘$somename’, valid in the -referenced table. - - When NAME has the format ‘@ROW$COLUMN’, it is substituted with the -name or ID found in this field of the current table. For example -‘remote($1, @@>$2)’ ⇒ ‘remote(year_2013, @@>$1)’. The format ‘B3’ is -not supported because it can not be distinguished from a plain table -name or ID. - - ---------- Footnotes ---------- - - (1) Org understands references typed by the user as ‘B4’, but it does -not use this syntax when offering a formula for editing. You can -customize this behavior using the variable -‘org-table-use-standard-references’. - - (2) The computation time scales as O(N^2) because table FOO is parsed -for each field to be copied. - - (3) The file ‘constants.el’ can supply the values of constants in two -different unit systems, ‘SI’ and ‘cgs’. Which one is used depends on -the value of the variable ‘constants-unit-system’. You can use the -‘STARTUP’ options ‘constSI’ and ‘constcgs’ to set this value for the -current buffer. - - -File: org.info, Node: Formula syntax for Calc, Next: Formula syntax for Lisp, Prev: References, Up: The Spreadsheet - -3.5.2 Formula syntax for Calc ------------------------------ - -A formula can be any algebraic expression understood by the Emacs Calc -package. Note that Calc has the non-standard convention that ‘/’ has -lower precedence than ‘*’, so that ‘a/b*c’ is interpreted as -‘(a/(b*c))’. Before evaluation by ‘calc-eval’ (see *note Calling Calc -from Your Lisp Programs: (calc)Calling Calc from Your Programs.), -variable substitution takes place according to the rules described -above. - - The range vectors can be directly fed into the Calc vector functions -like ‘vmean’ and ‘vsum’. - - A formula can contain an optional mode string after a semicolon. -This string consists of flags to influence Calc and other modes during -execution. By default, Org uses the standard Calc modes (precision 12, -angular units degrees, fraction and symbolic modes off). The display -format, however, has been changed to ‘(float 8)’ to keep tables compact. -The default settings can be configured using the variable -‘org-calc-default-modes’. - -‘p20’ - Set the internal Calc calculation precision to 20 digits. - -‘n3’, ‘s3’, ‘e2’, ‘f4’ - Normal, scientific, engineering or fixed format of the result of - Calc passed back to Org. Calc formatting is unlimited in precision - as long as the Calc calculation precision is greater. - -‘D’, ‘R’ - Degree and radian angle modes of Calc. - -‘F’, ‘S’ - Fraction and symbolic modes of Calc. - -‘u’ - Units simplification mode of Calc. Calc is also a symbolic - calculator and is capable of working with values having a unit, - represented with numerals followed by a unit string in Org table - cells. This mode instructs Calc to simplify the units in the - computed expression before returning the result. - -‘T’, ‘t’, ‘U’ - Duration computations in Calc or Lisp, *note Durations and time - values::. - -‘E’ - If and how to consider empty fields. Without ‘E’ empty fields in - range references are suppressed so that the Calc vector or Lisp - list contains only the non-empty fields. With ‘E’ the empty fields - are kept. For empty fields in ranges or empty field references the - value ‘nan’ (not a number) is used in Calc formulas and the empty - string is used for Lisp formulas. Add ‘N’ to use 0 instead for - both formula types. For the value of a field the mode ‘N’ has - higher precedence than ‘E’. - -‘N’ - Interpret all fields as numbers, use 0 for non-numbers. See the - next section to see how this is essential for computations with - Lisp formulas. In Calc formulas it is used only occasionally - because there number strings are already interpreted as numbers - without ‘N’. - -‘L’ - Literal, for Lisp formulas only. See the next section. - - Unless you use large integer numbers or high-precision calculation -and display for floating point numbers you may alternatively provide a -‘printf’ format specifier to reformat the Calc result after it has been -passed back to Org instead of letting Calc already do the formatting(1). -A few examples: - -‘$1+$2’ Sum of first and second field -‘$1+$2;%.2f’ Same, format result to two decimals -‘exp($2)+exp($1)’ Math functions can be used -‘$0;%.1f’ Reformat current cell to 1 decimal -‘($3-32)*5/9’ Degrees F → C conversion -‘$c/$1/$cm’ Hz → cm conversion, using ‘constants.el’ -‘tan($1);Dp3s1’ Compute in degrees, precision 3, display SCI 1 -‘sin($1);Dp3%.1e’ Same, but use ‘printf’ specifier for display -‘vmean($2..$7)’ Compute column range mean, using vector function -‘vmean($2..$7);EN’ Same, but treat empty fields as 0 -‘taylor($3,x=7,2)’ Taylor series of $3, at x=7, second degree - - Calc also contains a complete set of logical operations (see *note -Logical Operations: (calc)Logical Operations.). For example - -‘if($1 < 20, teen, string(""))’ - ‘"teen"’ if age ‘$1’ is less than 20, else the Org table result - field is set to empty with the empty string. - -‘if("$1" == "nan" || "$2" == "nan", string(""), $1 + $2); E f-1’ - Sum of the first two columns. When at least one of the input - fields is empty the Org table result field is set to empty. ‘E’ is - required to not convert empty fields to 0. ‘f-1’ is an optional - Calc format string similar to ‘%.1f’ but leaves empty results - empty. - -‘if(typeof(vmean($1..$7)) == 12, string(""), vmean($1..$7); E’ - Mean value of a range unless there is any empty field. Every field - in the range that is empty is replaced by ‘nan’ which lets ‘vmean’ - result in ‘nan’. Then ‘typeof =’ 12= detects the ‘nan’ from - ‘vmean’ and the Org table result field is set to empty. Use this - when the sample set is expected to never have missing values. - -‘if("$1..$7" == "[]", string(""), vmean($1..$7))’ - Mean value of a range with empty fields skipped. Every field in - the range that is empty is skipped. When all fields in the range - are empty the mean value is not defined and the Org table result - field is set to empty. Use this when the sample set can have a - variable size. - -‘vmean($1..$7); EN’ - To complete the example before: Mean value of a range with empty - fields counting as samples with value 0. Use this only when - incomplete sample sets should be padded with 0 to the full size. - - You can add your own Calc functions defined in Emacs Lisp with -‘defmath’ and use them in formula syntax for Calc. - - ---------- Footnotes ---------- - - (1) The printf reformatting is limited in precision because the value -passed to it is converted into an “integer” or “double”. The “integer” -is limited in size by truncating the signed value to 32 bits. The -“double” is limited in precision to 64 bits overall which leaves -approximately 16 significant decimal digits. - - -File: org.info, Node: Formula syntax for Lisp, Next: Durations and time values, Prev: Formula syntax for Calc, Up: The Spreadsheet - -3.5.3 Emacs Lisp forms as formulas ----------------------------------- - -It is also possible to write a formula in Emacs Lisp. This can be -useful for string manipulation and control structures, if Calc’s -functionality is not enough. - - A formula is evaluated as a Lisp form when it starts with a -single-quote followed by an opening parenthesis. Cell table references -are interpolated into the Lisp form before execution. The evaluation -should return either a string or a number. Evaluation modes and a -‘printf’ format used to render the returned values can be specified -after a semicolon. - - By default, references are interpolated as literal Lisp strings: the -field content is replaced in the Lisp form stripped of leading and -trailing white space and surrounded in double-quotes. For example: - - '(concat $1 $2) - -concatenates the content of columns 1 and column 2. - - When the ‘N’ flag is used, all referenced elements are parsed as -numbers and interpolated as Lisp numbers, without quotes. Fields that -cannot be parsed as numbers are interpolated as zeros. For example: - - '(+ $1 $2);N - -adds columns 1 and 2, equivalent to Calc’s ‘$1+$2’. Ranges are inserted -as space-separated fields, so they can be embedded in list or vector -syntax. For example: - - '(apply '+ '($1..$4));N - -computes the sum of columns 1 to 4, like Calc’s ‘vsum($1..$4)’. - - When the ‘L’ flag is used, all fields are interpolated literally: the -cell content is replaced in the Lisp form stripped of leading and -trailing white space and without quotes. If a reference is intended to -be interpreted as a string by the Lisp form, the reference operator -itself should be enclosed in double-quotes, like ‘"$3"’. The ‘L’ flag -is useful when strings and numbers are used in the same Lisp form. For -example: - - '(substring "$1" $2 $3);L - -extracts the part of the string in column 1 between the character -positions specified in the integers in column 2 and 3 and it is easier -to read than the equivalent: - - '(substring $1 (string-to-number $2) (string-to-number $3)) - - -File: org.info, Node: Durations and time values, Next: Field and range formulas, Prev: Formula syntax for Lisp, Up: The Spreadsheet - -3.5.4 Durations and time values -------------------------------- - -If you want to compute time values use the ‘T’, ‘t’, or ‘U’ flag, either -in Calc formulas or Elisp formulas: - - | Task 1 | Task 2 | Total | - |---------+----------+----------| - | 2:12 | 1:47 | 03:59:00 | - | 2:12 | 1:47 | 03:59 | - | 3:02:20 | -2:07:00 | 0.92 | - #+TBLFM: @2$3=$1+$2;T::@3$3=$1+$2;U::@4$3=$1+$2;t - - Input duration values must be of the form ‘HH:MM[:SS]’, where seconds -are optional. With the ‘T’ flag, computed durations are displayed as -‘HH:MM:SS’ (see the first formula above). With the ‘U’ flag, seconds -are omitted so that the result is only ‘HH:MM’ (see second formula -above). Zero-padding of the hours field depends upon the value of the -variable ‘org-table-duration-hour-zero-padding’. - - With the ‘t’ flag, computed durations are displayed according to the -value of the option ‘org-table-duration-custom-format’, which defaults -to ‘hours’ and displays the result as a fraction of hours (see the third -formula in the example above). - - Negative duration values can be manipulated as well, and integers are -considered as seconds in addition and subtraction. - - -File: org.info, Node: Field and range formulas, Next: Column formulas, Prev: Durations and time values, Up: The Spreadsheet - -3.5.5 Field and range formulas ------------------------------- - -To assign a formula to a particular field, type it directly into the -field, preceded by ‘:=’, for example ‘vsum(@II..III)’. When you press -‘<TAB>’ or ‘<RET>’ or ‘C-c C-c’ with point still in the field, the -formula is stored as the formula for this field, evaluated, and the -current field is replaced with the result. - - Formulas are stored in a special ‘TBLFM’ keyword located directly -below the table. If you type the equation in the fourth field of the -third data line in the table, the formula looks like ‘@3$4=$1+$2’. When -inserting/deleting/swapping column and rows with the appropriate -commands, _absolute references_ (but not relative ones) in stored -formulas are modified in order to still reference the same field. To -avoid this from happening, in particular in range references, anchor -ranges at the table borders (using ‘@<’, ‘@>’, ‘$<’, ‘$>’), or at hlines -using the ‘@I’ notation. Automatic adaptation of field references does -not happen if you edit the table structure with normal editing -commands—you must fix the formulas yourself. - - Instead of typing an equation into the field, you may also use the -following command - -‘C-u C-c =’ (‘org-table-eval-formula’) - Install a new formula for the current field. The command prompts - for a formula with default taken from the ‘TBLFM’ keyword, applies - it to the current field, and stores it. - - The left-hand side of a formula can also be a special expression in -order to assign the formula to a number of different fields. There is -no keyboard shortcut to enter such range formulas. To add them, use the -formula editor (see *note Editing and debugging formulas::) or edit the -‘TBLFM’ keyword directly. - -‘$2=’ - Column formula, valid for the entire column. This is so common - that Org treats these formulas in a special way, see *note Column - formulas::. - -‘@3=’ - Row formula, applies to all fields in the specified row. ‘@>=’ - means the last row. - -‘@1$2..@4$3=’ - Range formula, applies to all fields in the given rectangular - range. This can also be used to assign a formula to some but not - all fields in a row. - -‘$NAME=’ - Named field, see *note Advanced features::. - - -File: org.info, Node: Column formulas, Next: Lookup functions, Prev: Field and range formulas, Up: The Spreadsheet - -3.5.6 Column formulas ---------------------- - -When you assign a formula to a simple column reference like ‘$3=’, the -same formula is used in all fields of that column, with the following -very convenient exceptions: (i) If the table contains horizontal -separator hlines with rows above and below, everything before the first -such hline is considered part of the table _header_ and is not modified -by column formulas. Therefore a header is mandatory when you use column -formulas and want to add hlines to group rows, like for example to -separate a total row at the bottom from the summand rows above. (ii) -Fields that already get a value from a field/range formula are left -alone by column formulas. These conditions make column formulas very -easy to use. - - To assign a formula to a column, type it directly into any field in -the column, preceded by an equal sign, like ‘=$1+$2’. When you press -‘<TAB>’ or ‘<RET>’ or ‘C-c C-c’ with point still in the field, the -formula is stored as the formula for the current column, evaluated and -the current field replaced with the result. If the field contains only -‘=’, the previously stored formula for this column is used. For each -column, Org only remembers the most recently used formula. In the -‘TBLFM’ keyword, column formulas look like ‘$4=$1+$2’. The left-hand -side of a column formula can not be the name of column, it must be the -numeric column reference or ‘$>’. - - Instead of typing an equation into the field, you may also use the -following command: - -‘C-c =’ (‘org-table-eval-formula’) - Install a new formula for the current column and replace current - field with the result of the formula. The command prompts for a - formula, with default taken from the ‘TBLFM’ keyword, applies it to - the current field and stores it. With a numeric prefix argument, - e.g., ‘C-5 C-c =’, the command applies it to that many consecutive - fields in the current column. - - -File: org.info, Node: Lookup functions, Next: Editing and debugging formulas, Prev: Column formulas, Up: The Spreadsheet - -3.5.7 Lookup functions ----------------------- - -Org has three predefined Emacs Lisp functions for lookups in tables. - -‘(org-lookup-first VAL S-LIST R-LIST &optional PREDICATE)’ - Searches for the first element S in list S-LIST for which - (PREDICATE VAL S) - is non-‘nil’; returns the value from the corresponding position in - list R-LIST. The default PREDICATE is ‘equal’. Note that the - parameters VAL and S are passed to PREDICATE in the same order as - the corresponding parameters are in the call to ‘org-lookup-first’, - where VAL precedes S-LIST. If R-LIST is ‘nil’, the matching - element S of S-LIST is returned. - -‘(org-lookup-last VAL S-LIST R-LIST &optional PREDICATE)’ - Similar to ‘org-lookup-first’ above, but searches for the _last_ - element for which PREDICATE is non-‘nil’. - -‘(org-lookup-all VAL S-LIST R-LIST &optional PREDICATE)’ - Similar to ‘org-lookup-first’, but searches for _all_ elements for - which PREDICATE is non-‘nil’, and returns _all_ corresponding - values. This function can not be used by itself in a formula, - because it returns a list of values. However, powerful lookups can - be built when this function is combined with other Emacs Lisp - functions. - - If the ranges used in these functions contain empty fields, the ‘E’ -mode for the formula should usually be specified: otherwise empty fields -are not included in S-LIST and/or R-LIST which can, for example, result -in an incorrect mapping from an element of S-LIST to the corresponding -element of R-LIST. - - These three functions can be used to implement associative arrays, -count matching cells, rank results, group data, etc. For practical -examples see this tutorial on Worg -(https://orgmode.org/worg/org-tutorials/org-lookups.html). - - -File: org.info, Node: Editing and debugging formulas, Next: Updating the table, Prev: Lookup functions, Up: The Spreadsheet - -3.5.8 Editing and debugging formulas ------------------------------------- - -You can edit individual formulas in the minibuffer or directly in the -field. Org can also prepare a special buffer with all active formulas -of a table. When offering a formula for editing, Org converts -references to the standard format (like ‘B3’ or ‘D&’) if possible. If -you prefer to only work with the internal format (like ‘@3$2’ or ‘$4’), -configure the variable ‘org-table-use-standard-references’. - -‘C-c =’ or ‘C-u C-c =’ (‘org-table-eval-formula’) - Edit the formula associated with the current column/field in the - minibuffer. See *note Column formulas::, and *note Field and range - formulas::. - -‘C-u C-u C-c =’ (‘org-table-eval-formula’) - Re-insert the active formula (either a field formula, or a column - formula) into the current field, so that you can edit it directly - in the field. The advantage over editing in the minibuffer is that - you can use the command ‘C-c ?’. - -‘C-c ?’ (‘org-table-field-info’) - While editing a formula in a table field, highlight the field(s) - referenced by the reference at point position in the formula. - -‘C-c }’ (‘org-table-toggle-coordinate-overlays’) - Toggle the display of row and column numbers for a table, using - overlays. These are updated each time the table is aligned; you - can force it with ‘C-c C-c’. - -‘C-c {’ (‘org-table-toggle-formula-debugger’) - Toggle the formula debugger on and off. See below. - -‘C-c '’ (‘org-table-edit-formulas’) - Edit all formulas for the current table in a special buffer, where - the formulas are displayed one per line. If the current field has - an active formula, point in the formula editor marks it. While - inside the special buffer, Org automatically highlights any field - or range reference at point position. You may edit, remove and add - formulas, and use the following commands: - - ‘C-c C-c’ or ‘C-x C-s’ (‘org-table-fedit-finish’) - Exit the formula editor and store the modified formulas. With - ‘C-u’ prefix, also apply the new formulas to the entire table. - - ‘C-c C-q’ (‘org-table-fedit-abort’) - Exit the formula editor without installing changes. - - ‘C-c C-r’ (‘org-table-fedit-toggle-ref-type’) - Toggle all references in the formula editor between standard - (like ‘B3’) and internal (like ‘@3$2’). - - ‘<TAB>’ (‘org-table-fedit-lisp-indent’) - Pretty-print or indent Lisp formula at point. When in a line - containing a Lisp formula, format the formula according to - Emacs Lisp rules. Another ‘<TAB>’ collapses the formula back - again. In the open formula, ‘<TAB>’ re-indents just like in - Emacs Lisp mode. - - ‘M-<TAB>’ (‘lisp-complete-symbol’) - Complete Lisp symbols, just like in Emacs Lisp mode. - - ‘S-<UP>’, ‘S-<DOWN>’, ‘S-<LEFT>’, ‘S-<RIGHT>’ - Shift the reference at point. For example, if the reference - is ‘B3’ and you press ‘S-<RIGHT>’, it becomes ‘C3’. This also - works for relative references and for hline references. - - ‘M-S-<UP>’ (‘org-table-fedit-line-up’) - Move the test line for column formulas up in the Org buffer. - - ‘M-S-<DOWN>’ (‘org-table-fedit-line-down’) - Move the test line for column formulas down in the Org buffer. - - ‘M-<UP>’ (‘org-table-fedit-scroll-up’) - Scroll up the window displaying the table. - - ‘M-<DOWN>’ (‘org-table-fedit-scroll-down’) - Scroll down the window displaying the table. - - ‘C-c }’ - Turn the coordinate grid in the table on and off. - - Making a table field blank does not remove the formula associated -with the field, because that is stored in a different line—the ‘TBLFM’ -keyword line. During the next recalculation, the field will be filled -again. To remove a formula from a field, you have to give an empty -reply when prompted for the formula, or to edit the ‘TBLFM’ keyword. - - You may edit the ‘TBLFM’ keyword directly and re-apply the changed -equations with ‘C-c C-c’ in that line or with the normal recalculation -commands in the table. - -Using multiple ‘TBLFM’ lines -............................ - -You may apply the formula temporarily. This is useful when you want to -switch the formula applied to the table. Place multiple ‘TBLFM’ -keywords right after the table, and then press ‘C-c C-c’ on the formula -to apply. Here is an example: - - | x | y | - |---+---| - | 1 | | - | 2 | | - #+TBLFM: $2=$1*1 - #+TBLFM: $2=$1*2 - -Pressing ‘C-c C-c’ in the line of ‘#+TBLFM: $2=$1*2’ yields: - - | x | y | - |---+---| - | 1 | 2 | - | 2 | 4 | - #+TBLFM: $2=$1*1 - #+TBLFM: $2=$1*2 - -If you recalculate this table, with ‘C-u C-c *’, for example, you get -the following result from applying only the first ‘TBLFM’ keyword. - - | x | y | - |---+---| - | 1 | 1 | - | 2 | 2 | - #+TBLFM: $2=$1*1 - #+TBLFM: $2=$1*2 - -Debugging formulas -.................. - -When the evaluation of a formula leads to an error, the field content -becomes the string ‘#ERROR’. If you would like to see what is going on -during variable substitution and calculation in order to find a bug, -turn on formula debugging in the Tbl menu and repeat the calculation, -for example by pressing ‘C-u C-u C-c = <RET>’ in a field. Detailed -information are displayed. - - -File: org.info, Node: Updating the table, Next: Advanced features, Prev: Editing and debugging formulas, Up: The Spreadsheet - -3.5.9 Updating the table ------------------------- - -Recalculation of a table is normally not automatic, but needs to be -triggered by a command. To make recalculation at least semi-automatic, -see *note Advanced features::. - - In order to recalculate a line of a table or the entire table, use -the following commands: - -‘C-c *’ (‘org-table-recalculate’) - Recalculate the current row by first applying the stored column - formulas from left to right, and all field/range formulas in the - current row. - -‘C-u C-c *’ or ‘C-u C-c C-c’ - Recompute the entire table, line by line. Any lines before the - first hline are left alone, assuming that these are part of the - table header. - -‘C-u C-u C-c *’ or ‘C-u C-u C-c C-c’ (‘org-table-iterate’) - Iterate the table by recomputing it until no further changes occur. - This may be necessary if some computed fields use the value of - other fields that are computed _later_ in the calculation sequence. - -‘M-x org-table-recalculate-buffer-tables’ - Recompute all tables in the current buffer. - -‘M-x org-table-iterate-buffer-tables’ - Iterate all tables in the current buffer, in order to converge - table-to-table dependencies. - - -File: org.info, Node: Advanced features, Prev: Updating the table, Up: The Spreadsheet - -3.5.10 Advanced features ------------------------- - -If you want the recalculation of fields to happen automatically, or if -you want to be able to assign _names_(1) to fields and columns, you need -to reserve the first column of the table for special marking characters. - -‘C-#’ (‘org-table-rotate-recalc-marks’) - Rotate the calculation mark in first column through the states ‘#’, - ‘*’, ‘!’, ‘$’. When there is an active region, change all marks in - the region. - - Here is an example of a table that collects exam results of students -and makes use of these features: - - |---+---------+--------+--------+--------+-------+------| - | | Student | Prob 1 | Prob 2 | Prob 3 | Total | Note | - |---+---------+--------+--------+--------+-------+------| - | ! | | P1 | P2 | P3 | Tot | | - | # | Maximum | 10 | 15 | 25 | 50 | 10.0 | - | ^ | | m1 | m2 | m3 | mt | | - |---+---------+--------+--------+--------+-------+------| - | # | Peter | 10 | 8 | 23 | 41 | 8.2 | - | # | Sam | 2 | 4 | 3 | 9 | 1.8 | - |---+---------+--------+--------+--------+-------+------| - | | Average | | | | 25.0 | | - | ^ | | | | | at | | - | $ | max=50 | | | | | | - |---+---------+--------+--------+--------+-------+------| - #+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f::$at=vmean(@-II..@-I);%.1f - - Important: Please note that for these special tables, recalculating - the table with ‘C-u C-c *’ only affects rows that are marked ‘#’ or - ‘*’, and fields that have a formula assigned to the field itself. - The column formulas are not applied in rows with empty first field. - - The marking characters have the following meaning: - -‘!’ - The fields in this line define names for the columns, so that you - may refer to a column as ‘$Tot’ instead of ‘$6’. - -‘^’ - This row defines names for the fields _above_ the row. With such a - definition, any formula in the table may use ‘$m1’ to refer to the - value ‘10’. Also, if you assign a formula to a names field, it is - stored as ‘$name = ...’. - -‘_’ - Similar to ‘^’, but defines names for the fields in the row - _below_. - -‘$’ - Fields in this row can define _parameters_ for formulas. For - example, if a field in a ‘$’ row contains ‘max=50’, then formulas - in this table can refer to the value 50 using ‘$max’. Parameters - work exactly like constants, only that they can be defined on a - per-table basis. - -‘#’ - Fields in this row are automatically recalculated when pressing - ‘<TAB>’ or ‘<RET>’ or ‘S-<TAB>’ in this row. Also, this row is - selected for a global recalculation with ‘C-u C-c *’. Unmarked - lines are left alone by this command. - -‘*’ - Selects this line for global recalculation with ‘C-u C-c *’, but - not for automatic recalculation. Use this when automatic - recalculation slows down editing too much. - -‘/’ - Do not export this line. Useful for lines that contain the - narrowing ‘<N>’ markers or column group markers. - - Finally, just to whet your appetite for what can be done with the -fantastic Calc package, here is a table that computes the Taylor series -of degree n at location x for a couple of functions. - - |---+-------------+---+-----+--------------------------------------| - | | Func | n | x | Result | - |---+-------------+---+-----+--------------------------------------| - | # | exp(x) | 1 | x | 1 + x | - | # | exp(x) | 2 | x | 1 + x + x^2 / 2 | - | # | exp(x) | 3 | x | 1 + x + x^2 / 2 + x^3 / 6 | - | # | x^2+sqrt(x) | 2 | x=0 | x*(0.5 / 0) + x^2 (2 - 0.25 / 0) / 2 | - | # | x^2+sqrt(x) | 2 | x=1 | 2 + 2.5 x - 2.5 + 0.875 (x - 1)^2 | - | * | tan(x) | 3 | x | 0.0175 x + 1.77e-6 x^3 | - |---+-------------+---+-----+--------------------------------------| - #+TBLFM: $5=taylor($2,$4,$3);n3 - - ---------- Footnotes ---------- - - (1) Such names must start with an alphabetic character and use only -alphanumeric/underscore characters. - - -File: org.info, Node: Org Plot, Prev: The Spreadsheet, Up: Tables - -3.6 Org Plot -============ - -Org Plot can produce graphs of information stored in Org tables, either -graphically or in ASCII art. - -Graphical plots using Gnuplot ------------------------------ - -Org Plot can produce 2D and 3D graphs of information stored in Org -tables using Gnuplot (https://www.gnuplot.info/) and Gnuplot mode -(http://cars9.uchicago.edu/~ravel/software/gnuplot-mode.html). To see -this in action, ensure that you have both Gnuplot and Gnuplot mode -installed on your system, then call ‘C-c " g’ or ‘M-x org-plot/gnuplot’ -on the following table. - - #+PLOT: title:"Citas" ind:1 deps:(3) type:2d with:histograms set:"yrange [0:]" - | Sede | Max cites | H-index | - |-----------+-----------+---------| - | Chile | 257.72 | 21.39 | - | Leeds | 165.77 | 19.68 | - | Sao Paolo | 71.00 | 11.50 | - | Stockholm | 134.19 | 14.33 | - | Morelia | 257.56 | 17.67 | - - Org Plot supports a range of plot types, and provides the ability to -add more. For example, a radar plot can be generated like so: - #+PLOT: title:"An evaluation of plaintext document formats" transpose:yes type:radar min:0 max:4 - | Format | Fine-grained-control | Initial Effort | Syntax simplicity | Editor Support | Integrations | Ease-of-referencing | Versatility | - |-------------------+----------------------+----------------+-------------------+----------------+--------------+---------------------+-------------| - | Word | 2 | 4 | 4 | 2 | 3 | 2 | 2 | - | LaTeX | 4 | 1 | 1 | 3 | 2 | 4 | 3 | - | Org Mode | 4 | 2 | 3.5 | 1 | 4 | 4 | 4 | - | Markdown | 1 | 3 | 3 | 4 | 3 | 3 | 1 | - | Markdown + Pandoc | 2.5 | 2.5 | 2.5 | 3 | 3 | 3 | 2 | - - Notice that Org Plot is smart enough to apply the table’s headers as -labels. Further control over the labels, type, content, and appearance -of plots can be exercised through the ‘PLOT’ keyword preceding a table. -See below for a complete list of Org Plot options. For more information -and examples see the Org Plot tutorial -(https://orgmode.org/worg/org-tutorials/org-plot.html). - -Plot options -............ - -‘set’ - Specify any Gnuplot option to be set when graphing. - -‘title’ - Specify the title of the plot. - -‘ind’ - Specify which column of the table to use as the ‘x’ axis. - -‘deps’ - Specify the columns to graph as a Lisp style list, surrounded by - parentheses and separated by spaces for example ‘dep:(3 4)’ to - graph the third and fourth columns. Defaults to graphing all other - columns aside from the ‘ind’ column. - -transpose - When ‘y’, ‘yes’, or ‘t’ attempt to transpose the table data before - plotting. Also recognises the shorthand option ‘trans’. - -‘type’ - Specify the type of the plot, by default one of ‘2d’, ‘3d’, - ‘radar’, or ‘grid’. Available types can be customised with - ‘org-plot/preset-plot-types’. - -‘with’ - Specify a ‘with’ option to be inserted for every column being - plotted, e.g., ‘lines’, ‘points’, ‘boxes’, ‘impulses’. Defaults to - ‘lines’. - -‘file’ - If you want to plot to a file, specify - ‘"path/to/desired/output-file"’. - -‘labels’ - List of labels to be used for the ‘deps’. Defaults to the column - headers if they exist. - -‘line’ - Specify an entire line to be inserted in the Gnuplot script. - -‘map’ - When plotting ‘3d’ or ‘grid’ types, set this to ‘t’ to graph a flat - mapping rather than a ‘3d’ slope. - -min - Provides a minimum axis value that may be used by a plot type. - Implicitly assumes the ‘y’ axis is being referred to. Can - explicitly provide a value for a either the ‘x’ or ‘y’ axis with - ‘xmin’ and ‘ymin’. - -max - Provides a maximum axis value that may be used by a plot type. - Implicitly assumes the ‘y’ axis is being referred to. Can - explicitly provide a value for a either the ‘x’ or ‘y’ axis with - ‘xmax’ and ‘ymax’. - -ticks - Provides a desired number of axis ticks to display, that may be - used by a plot type. If none is given a plot type that requires - ticks will use ‘org--plot/sensible-tick-num’ to try to determine a - good value. - -‘timefmt’ - Specify format of Org mode timestamps as they will be parsed by - Gnuplot. Defaults to ‘%Y-%m-%d-%H:%M:%S’. - -‘script’ - If you want total control, you can specify a script file—place the - file name between double-quotes—which will be used to plot. Before - plotting, every instance of ‘$datafile’ in the specified script - will be replaced with the path to the generated data file. Note: - even if you set this option, you may still want to specify the plot - type, as that can impact the content of the data file. - -ASCII bar plots ---------------- - -While point is on a column, typing ‘C-c `` a’ or ‘M-x orgtbl-ascii-plot’ -create a new column containing an ASCII-art bars plot. The plot is -implemented through a regular column formula. When the source column -changes, the bar plot may be updated by refreshing the table, for -example typing ‘C-u C-c *’. - - | Sede | Max cites | | - |---------------+-----------+--------------| - | Chile | 257.72 | WWWWWWWWWWWW | - | Leeds | 165.77 | WWWWWWWh | - | Sao Paolo | 71.00 | WWW; | - | Stockholm | 134.19 | WWWWWW: | - | Morelia | 257.56 | WWWWWWWWWWWH | - | Rochefourchat | 0.00 | | - #+TBLFM: $3='(orgtbl-ascii-draw $2 0.0 257.72 12) - - The formula is an Elisp call. - - -- Function: orgtbl-ascii-draw value min max &optional width - Draw an ASCII bar in a table. - - VALUE is the value to plot. - - MIN is the value displayed as an empty bar. MAX is the value - filling all the WIDTH. Sources values outside this range are - displayed as ‘too small’ or ‘too large’. - - WIDTH is the number of characters of the bar plot. It defaults to - ‘12’. - - -File: org.info, Node: Hyperlinks, Next: TODO Items, Prev: Tables, Up: Top - -4 Hyperlinks -************ - -Like HTML, Org provides support for links inside a file, external links -to other files, Usenet articles, emails, and much more. - -* Menu: - -* Link Format:: How links in Org are formatted. -* Internal Links:: Links to other places in the current file. -* Radio Targets:: Make targets trigger links in plain text. -* External Links:: URL-like links to the world. -* Handling Links:: Creating, inserting and following. -* Using Links Outside Org:: Linking from my C source code? -* Link Abbreviations:: Shortcuts for writing complex links. -* Search Options:: Linking to a specific location. -* Custom Searches:: When the default search is not enough. - - -File: org.info, Node: Link Format, Next: Internal Links, Up: Hyperlinks - -4.1 Link Format -=============== - -Org recognizes plain URIs, possibly wrapped within angle brackets(1), -and activate them as clickable links. - - The general link format, however, looks like this: - - [[LINK][DESCRIPTION]] - -or alternatively - - [[LINK]] - - Some ‘\’, ‘[’ and ‘]’ characters in the LINK part need to be -“escaped”, i.e., preceded by another ‘\’ character. More specifically, -the following characters, and only them, must be escaped: - - 1. all ‘[’ and ‘]’ characters, - 2. every ‘\’ character preceding either ‘]’ or ‘[’, - 3. every ‘\’ character at the end of the link. - - Functions inserting links (see *note Handling Links::) properly -escape ambiguous characters. You only need to bother about the rules -above when inserting directly, or yanking, a URI within square brackets. -When in doubt, you may use the function ‘org-link-escape’, which turns a -link string into its escaped form. - - Once a link in the buffer is complete, with all brackets present, Org -changes the display so that ‘DESCRIPTION’ is displayed instead of -‘[[LINK][DESCRIPTION]]’ and ‘LINK’ is displayed instead of ‘[[LINK]]’. -Links are highlighted in the ‘org-link’ face, which, by default, is an -underlined face. - - You can directly edit the visible part of a link. This can be either -the LINK part, if there is no description, or the DESCRIPTION part -otherwise. To also edit the invisible LINK part, use ‘C-c C-l’ with -point on the link (see *note Handling Links::). - - If you place point at the beginning or just behind the end of the -displayed text and press ‘<BS>’, you remove the—invisible—bracket at -that location(2). This makes the link incomplete and the internals are -again displayed as plain text. Inserting the missing bracket hides the -link internals again. To show the internal structure of all links, use -the menu: Org → Hyperlinks → Literal links. - - ---------- Footnotes ---------- - - (1) Plain URIs are recognized only for a well-defined set of schemes. -See *note External Links::. Unlike URI syntax, they cannot contain -parenthesis or white spaces, either. URIs within angle brackets have no -such limitation. - - (2) More accurately, the precise behavior depends on how point -arrived there—see *note Invisible Text: (elisp)Invisible Text. - - -File: org.info, Node: Internal Links, Next: Radio Targets, Prev: Link Format, Up: Hyperlinks - -4.2 Internal Links -================== - -A link that does not look like a URL—i.e., does not start with a known -scheme or a file name—refers to the current document. You can follow it -with ‘C-c C-o’ when point is on the link, or with a mouse click (see -*note Handling Links::). - - Org provides several refinements to internal navigation within a -document. Most notably, a construct like ‘[[#my-custom-id]]’ -specifically targets the entry with the ‘CUSTOM_ID’ property set to -‘my-custom-id’. Also, an internal link looking like ‘[[*Some section]]’ -points to a headline with the name ‘Some section’(1). - - When the link does not belong to any of the cases above, Org looks -for a _dedicated target_: the same string in double angular brackets, -like ‘<<My Target>>’. - - If no dedicated target exists, the link tries to match the exact name -of an element within the buffer. Naming is done, unsurprisingly, with -the ‘NAME’ keyword, which has to be put in the line before the element -it refers to, as in the following example - - #+NAME: My Target - | a | table | - |----+------------| - | of | four cells | - - Ultimately, if none of the above succeeds, Org searches for a -headline that is exactly the link text but may also include a TODO -keyword and tags, or initiates a plain text search, according to the -value of ‘org-link-search-must-match-exact-headline’. - - Note that you must make sure custom IDs, dedicated targets, and names -are unique throughout the document. Org provides a linter to assist you -in the process, if needed. See *note Org Syntax::. - - During export, internal links are used to mark objects and assign -them a number. Marked objects are then referenced by links pointing to -them. In particular, links without a description appear as the number -assigned to the marked object(2). In the following excerpt from an Org -buffer - - 1. one item - 2. <<target>>another item - Here we refer to item [[target]]. - -The last sentence will appear as ‘Here we refer to item 2’ when -exported. - - In non-Org files, the search looks for the words in the link text. -In the above example the search would be for ‘target’. - - Following a link pushes a mark onto Org’s own mark ring. You can -return to the previous position with ‘C-c &’. Using this command -several times in direct succession goes back to positions recorded -earlier. - - ---------- Footnotes ---------- - - (1) To insert a link targeting a headline, in-buffer completion can -be used. Just type a star followed by a few optional letters into the -buffer and press ‘M-<TAB>’. All headlines in the current buffer are -offered as completions. - - (2) When targeting a ‘NAME’ keyword, the ‘CAPTION’ keyword is -mandatory in order to get proper numbering (see *note Captions::). - - -File: org.info, Node: Radio Targets, Next: External Links, Prev: Internal Links, Up: Hyperlinks - -4.3 Radio Targets -================= - -Org can automatically turn any occurrences of certain target names in -normal text into a link. So without explicitly creating a link, the -text connects to the target radioing its position. Radio targets are -enclosed by triple angular brackets. For example, a target ‘<<<My -Target>>>’ causes each occurrence of ‘my target’ in normal text to -become activated as a link. The Org file is scanned automatically for -radio targets only when the file is first loaded into Emacs. To update -the target list during editing, press ‘C-c C-c’ with point on or at a -target. - - -File: org.info, Node: External Links, Next: Handling Links, Prev: Radio Targets, Up: Hyperlinks - -4.4 External Links -================== - -Org supports links to files, websites, Usenet and email messages, BBDB -database entries and links to both IRC conversations and their logs. -External links are URL-like locators. They start with a short -identifying string followed by a colon. There can be no space after the -colon. - - Here is the full set of built-in link types: - -‘file’ - File links. File name may be remote, absolute, or relative. - - Additionally, you can specify a line number, or a text search. In - Org files, you may link to a headline name, a custom ID, or a code - reference instead. - - As a special case, “file” prefix may be omitted if the file name is - complete, e.g., it starts with ‘./’, or ‘/’. - -‘attachment’ - Same as file links but for files and folders attached to the - current node (see *note Attachments::). Attachment links are - intended to behave exactly as file links but for files relative to - the attachment directory. - -‘bbdb’ - Link to a BBDB record, with possible regexp completion. - -‘docview’ - Link to a document opened with DocView mode. You may specify a - page number. - -‘doi’ - Link to an electronic resource, through its handle. - -‘elisp’ - Execute an Elisp command upon activation. - -‘gnus’, ‘rmail’, ‘mhe’ - Link to messages or folders from a given Emacs’ MUA. - -‘help’ - Display documentation of a symbol in ‘*Help*’ buffer. - -‘http’, ‘https’ - Web links. - -‘id’ - Link to a specific headline by its ID property, in an Org file. - -‘info’ - Link to an Info manual, or to a specific node. - -‘irc’ - Link to an IRC channel. - -‘mailto’ - Link to message composition. - -‘news’ - Usenet links. - -‘shell’ - Execute a shell command upon activation. - - The following table illustrates the link types above, along with -their options: - -Link Type Example ------------------------------------------------------------------------- -http ‘http://staff.science.uva.nl/c.dominik/’ -https ‘https://orgmode.org/’ -doi ‘doi:10.1000/182’ -file ‘file:/home/dominik/images/jupiter.jpg’ - ‘/home/dominik/images/jupiter.jpg’ (same as above) - ‘file:papers/last.pdf’ - ‘./papers/last.pdf’ (same as above) - ‘file:/ssh:me@some.where:papers/last.pdf’ (remote) - ‘/ssh:me@some.where:papers/last.pdf’ (same as above) - ‘file:sometextfile::NNN’ (jump to line number) - ‘file:projects.org’ - ‘file:projects.org::some words’ (text search)(1) - ‘file:projects.org::*task title’ (headline search) - ‘file:projects.org::#custom-id’ (headline search) -attachment ‘attachment:projects.org’ - ‘attachment:projects.org::some words’ (text search) -docview ‘docview:papers/last.pdf::NNN’ -id ‘id:B7423F4D-2E8A-471B-8810-C40F074717E9’ -news ‘news:comp.emacs’ -mailto ‘mailto:adent@galaxy.net’ -mhe ‘mhe:folder’ (folder link) - ‘mhe:folder#id’ (message link) -rmail ‘rmail:folder’ (folder link) - ‘rmail:folder#id’ (message link) -gnus ‘gnus:group’ (group link) - ‘gnus:group#id’ (article link) -bbdb ‘bbdb:R.*Stallman’ (record with regexp) -irc ‘irc:/irc.com/#emacs/bob’ -help ‘help:org-store-link’ -info ‘info:org#External links’ -shell ‘shell:ls *.org’ -elisp ‘elisp:(find-file "Elisp.org")’ (Elisp form to evaluate) - ‘elisp:org-agenda’ (interactive Elisp command) - - On top of these built-in link types, additional ones are available -through the ‘org-contrib’ repository (see *note Installation::). For -example, these links to VM or Wanderlust messages are available when you -load the corresponding libraries from the ‘org-contrib’ repository: - -‘vm:folder’ VM folder link -‘vm:folder#id’ VM message link -‘vm://myself@some.where.org/folder#id’ VM on remote machine -‘vm-imap:account:folder’ VM IMAP folder link -‘vm-imap:account:folder#id’ VM IMAP message link -‘wl:folder’ Wanderlust folder link -‘wl:folder#id’ Wanderlust message link - - For information on customizing Org to add new link types, see *note -Adding Hyperlink Types::. - - A link should be enclosed in double brackets and may contain -descriptive text to be displayed instead of the URL (see *note Link -Format::), for example: - - [[https://www.gnu.org/software/emacs/][GNU Emacs]] - - If the description is a file name or URL that points to an image, -HTML export (see *note HTML Export::) inlines the image as a clickable -button. If there is no description at all and the link points to an -image, that image is inlined into the exported HTML file. - - Org also recognizes external links amid normal text and activates -them as links. If spaces must be part of the link (for example in -‘bbdb:R.*Stallman’), or if you need to remove ambiguities about the end -of the link, enclose the link in square or angular brackets. - - ---------- Footnotes ---------- - - (1) The actual behavior of the search depends on the value of the -variable ‘org-link-search-must-match-exact-headline’. If its value is -‘nil’, then a fuzzy text search is done. If it is ‘t’, then only the -exact headline is matched, ignoring spaces and statistic cookies. If -the value is ‘query-to-create’, then an exact headline is searched; if -it is not found, then the user is queried to create it. - - -File: org.info, Node: Handling Links, Next: Using Links Outside Org, Prev: External Links, Up: Hyperlinks - -4.5 Handling Links -================== - -Org provides methods to create a link in the correct syntax, to insert -it into an Org file, and to follow the link. - - The main function is ‘org-store-link’, called with ‘M-x -org-store-link’. Because of its importance, we suggest to bind it to a -widely available key (see *note Activation::). It stores a link to the -current location. The link is stored for later insertion into an Org -buffer—see below. The kind of link that is created depends on the -current buffer: - -_Org mode buffers_ - For Org files, if there is a ‘<<target>>’ at point, the link points - to the target. Otherwise it points to the current headline, which - is also the description(1). - - If the headline has a ‘CUSTOM_ID’ property, store a link to this - custom ID. In addition or alternatively, depending on the value of - ‘org-id-link-to-org-use-id’, create and/or use a globally unique - ‘ID’ property for the link(2). So using this command in Org - buffers potentially creates two links: a human-readable link from - the custom ID, and one that is globally unique and works even if - the entry is moved from file to file. The ‘ID’ property can be - either a UUID (default) or a timestamp, depending on - ‘org-id-method’. Later, when inserting the link, you need to - decide which one to use. - -_Email/News clients: VM, Rmail, Wanderlust, MH-E, Gnus_ - Pretty much all Emacs mail clients are supported. The link points - to the current article, or, in some Gnus buffers, to the group. - The description is constructed according to the variable - ‘org-link-email-description-format’. By default, it refers to the - addressee and the subject. - -_Web browsers: W3, W3M and EWW_ - Here the link is the current URL, with the page title as the - description. - -_Contacts: BBDB_ - Links created in a BBDB buffer point to the current entry. - -_Chat: IRC_ - For IRC links, if the variable ‘org-irc-link-to-logs’ is non-‘nil’, - create a ‘file’ style link to the relevant point in the logs for - the current conversation. Otherwise store an ‘irc’ style link to - the user/channel/server under the point. - -_Other files_ - For any other file, the link points to the file, with a search - string (see *note Search Options::) pointing to the contents of the - current line. If there is an active region, the selected words - form the basis of the search string. You can write custom Lisp - functions to select the search string and perform the search for - particular file types (see *note Custom Searches::). - - You can also define dedicated links to other files. See *note - Adding Hyperlink Types::. - -_Agenda view_ - When point is in an agenda view, the created link points to the - entry referenced by the current line. - - From an Org buffer, the following commands create, navigate or, more -generally, act on links. - -‘C-c C-l’ (‘org-insert-link’) - Insert a link(3). This prompts for a link to be inserted into the - buffer. You can just type a link, using text for an internal link, - or one of the link type prefixes mentioned in the examples above. - The link is inserted into the buffer, along with a descriptive - text(4). If some text was selected at this time, it becomes the - default description. - - _Inserting stored links_ - All links stored during the current session are part of the - history for this prompt, so you can access them with ‘<UP>’ - and ‘<DOWN>’ (or ‘M-p’, ‘M-n’). - - _Completion support_ - Completion with ‘<TAB>’ helps you to insert valid link - prefixes like ‘http’ or ‘ftp’, including the prefixes defined - through link abbreviations (see *note Link Abbreviations::). - If you press ‘<RET>’ after inserting only the prefix, Org - offers specific completion support for some link types(5). - For example, if you type ‘f i l e <RET>’—alternative access: - ‘C-u C-c C-l’, see below—Org offers file name completion, and - after ‘b b d b <RET>’ you can complete contact names. - -‘C-u C-c C-l’ - When ‘C-c C-l’ is called with a ‘C-u’ prefix argument, insert a - link to a file. You may use file name completion to select the - name of the file. The path to the file is inserted relative to the - directory of the current Org file, if the linked file is in the - current directory or in a sub-directory of it, or if the path is - written relative to the current directory using ‘../’. Otherwise - an absolute path is used, if possible with ‘~/’ for your home - directory. You can force an absolute path with two ‘C-u’ prefixes. - -‘C-c C-l’ (with point on existing link) - When point is on an existing link, ‘C-c C-l’ allows you to edit the - link and description parts of the link. - -‘C-c C-o’ (‘org-open-at-point’) - Open link at point. This launches a web browser for URL (using - ‘browse-url-at-point’), run VM/MH-E/Wanderlust/Rmail/Gnus/BBDB for - the corresponding links, and execute the command in a shell link. - When point is on an internal link, this command runs the - corresponding search. When point is on the tags part of a - headline, it creates the corresponding tags view (see *note - Matching tags and properties::). If point is on a timestamp, it - compiles the agenda for that date. Furthermore, it visits text and - remote files in ‘file’ links with Emacs and select a suitable - application for local non-text files. Classification of files is - based on file extension only. See option ‘org-file-apps’. If you - want to override the default application and visit the file with - Emacs, use a ‘C-u’ prefix. If you want to avoid opening in Emacs, - use a ‘C-u C-u’ prefix. - - If point is on a headline, but not on a link, offer all links in - the headline and entry text. If you want to setup the frame - configuration for following links, customize - ‘org-link-frame-setup’. - -‘<RET>’ - When ‘org-return-follows-link’ is set, ‘<RET>’ also follows the - link at point. - -‘mouse-2’ or ‘mouse-1’ - On links, ‘mouse-1’ and ‘mouse-2’ opens the link just as ‘C-c C-o’ - does. - -‘mouse-3’ - Like ‘mouse-2’, but force file links to be opened with Emacs, and - internal links to be displayed in another window(6). - -‘C-c %’ (‘org-mark-ring-push’) - Push the current position onto the Org mark ring, to be able to - return easily. Commands following an internal link do this - automatically. - -‘C-c &’ (‘org-mark-ring-goto’) - Jump back to a recorded position. A position is recorded by the - commands following internal links, and by ‘C-c %’. Using this - command several times in direct succession moves through a ring of - previously recorded positions. - -‘C-c C-x C-n’ (‘org-next-link’) -‘C-c C-x C-p’ (‘org-previous-link’) - Move forward/backward to the next link in the buffer. At the limit - of the buffer, the search fails once, and then wraps around. The - key bindings for this are really too long; you might want to bind - this also to ‘M-n’ and ‘M-p’. - - (with-eval-after-load 'org - (define-key org-mode-map (kbd "M-n") #'org-next-link) - (define-key org-mode-map (kbd "M-p") #'org-previous-link)) - - ---------- Footnotes ---------- - - (1) If the headline contains a timestamp, it is removed from the -link, which results in a wrong link—you should avoid putting a timestamp -in the headline. - - (2) The Org Id library must first be loaded, either through -‘org-customize’, by enabling ‘id’ in ‘org-modules’, or by adding -‘(require 'org-id)’ in your Emacs init file. - - (3) Note that you do not have to use this command to insert a link. -Links in Org are plain text, and you can type or paste them straight -into the buffer. By using this command, the links are automatically -enclosed in double brackets, and you will be asked for the optional -descriptive text. - - (4) After insertion of a stored link, the link will be removed from -the list of stored links. To keep it in the list for later use, use a -triple ‘C-u’ prefix argument to ‘C-c C-l’, or configure the option -‘org-link-keep-stored-after-insertion’. - - (5) This works if a function has been defined in the ‘:complete’ -property of a link in ‘org-link-parameters’. - - (6) See the variable ‘org-link-use-indirect-buffer-for-internals’. - - -File: org.info, Node: Using Links Outside Org, Next: Link Abbreviations, Prev: Handling Links, Up: Hyperlinks - -4.6 Using Links Outside Org -=========================== - -You can insert and follow links that have Org syntax not only in Org, -but in any Emacs buffer. For this, Org provides two functions: -‘org-insert-link-global’ and ‘org-open-at-point-global’. - - You might want to bind them to globally available keys. See *note -Activation:: for some advice. - - -File: org.info, Node: Link Abbreviations, Next: Search Options, Prev: Using Links Outside Org, Up: Hyperlinks - -4.7 Link Abbreviations -====================== - -Long URL can be cumbersome to type, and often many similar links are -needed in a document. For this you can use link abbreviations. An -abbreviated link looks like this - - [[linkword:tag][description]] - -where the tag is optional. The _linkword_ must be a word, starting with -a letter, followed by letters, numbers, ‘-’, and ‘_’. Abbreviations are -resolved according to the information in the variable -‘org-link-abbrev-alist’ that relates the linkwords to replacement text. -Here is an example: - - (setq org-link-abbrev-alist - '(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=") - ("Nu Html Checker" . "https://validator.w3.org/nu/?doc=%h") - ("duckduckgo" . "https://duckduckgo.com/?q=%s") - ("omap" . "http://nominatim.openstreetmap.org/search?q=%s&polygon=1") - ("ads" . "https://ui.adsabs.harvard.edu/search/q=%20author%3A\"%s\""))) - - If the replacement text contains the string ‘%s’, it is replaced with -the tag. Using ‘%h’ instead of ‘%s’ percent-encodes the tag (see the -example above, where we need to encode the URL parameter). Using -‘%(my-function)’ passes the tag to a custom Lisp function, and replace -it by the resulting string. - - If the replacement text do not contain any specifier, it is simply -appended to the string in order to create the link. - - Instead of a string, you may also specify a Lisp function to create -the link. Such a function will be called with the tag as the only -argument. - - With the above setting, you could link to a specific bug with -‘[[bugzilla:129]]’, search the web for ‘OrgMode’ with -‘[[duckduckgo:OrgMode]]’, show the map location of the Free Software -Foundation ‘[[gmap:51 Franklin Street, Boston]]’ or of Carsten office -‘[[omap:Science Park 904, Amsterdam, The Netherlands]]’ and find out -what the Org author is doing besides Emacs hacking with -‘[[ads:Dominik,C]]’. - - If you need special abbreviations just for a single Org buffer, you -can define them in the file with - - #+LINK: bugzilla http://10.1.2.9/bugzilla/show_bug.cgi?id= - #+LINK: duckduckgo https://duckduckgo.com/?q=%s - - In-buffer completion (see *note Completion::) can be used after ‘[’ -to complete link abbreviations. You may also define a Lisp function -that implements special (e.g., completion) support for inserting such a -link with ‘C-c C-l’. Such a function should not accept any arguments, -and should return the full link with a prefix. You can set the link -completion function like this: - - (org-link-set-parameter "type" :complete #'some-completion-function) - - -File: org.info, Node: Search Options, Next: Custom Searches, Prev: Link Abbreviations, Up: Hyperlinks - -4.8 Search Options in File Links -================================ - -File links can contain additional information to make Emacs jump to a -particular location in the file when following a link. This can be a -line number or a search option after a double colon(1). For example, -when the command ‘org-store-link’ creates a link (see *note Handling -Links::) to a file, it encodes the words in the current line as a search -string that can be used to find this line back later when following the -link with ‘C-c C-o’. - - Note that all search options apply for Attachment links in the same -way that they apply for File links. - - Here is the syntax of the different ways to attach a search to a file -link, together with explanations for each: - - [[file:~/code/main.c::255]] - [[file:~/xx.org::My Target]] - [[file:~/xx.org::*My Target]] - [[file:~/xx.org::#my-custom-id]] - [[file:~/xx.org::/regexp/]] - [[attachment:main.c::255]] - -‘255’ - Jump to line 255. - -‘My Target’ - Search for a link target ‘<<My Target>>’, or do a text search for - ‘my target’, similar to the search in internal links, see *note - Internal Links::. In HTML export (see *note HTML Export::), such a - file link becomes a HTML reference to the corresponding named - anchor in the linked file. - -‘*My Target’ - In an Org file, restrict search to headlines. - -‘#my-custom-id’ - Link to a heading with a ‘CUSTOM_ID’ property - -‘/REGEXP/’ - Do a regular expression search for REGEXP (see *note Regular - Expressions::). This uses the Emacs command ‘occur’ to list all - matches in a separate window. If the target file is in Org mode, - ‘org-occur’ is used to create a sparse tree with the matches. - - As a degenerate case, a file link with an empty file name can be used -to search the current file. For example, ‘[[file:::find me]]’ does a -search for ‘find me’ in the current file, just as ‘[[find me]]’ would. - - ---------- Footnotes ---------- - - (1) For backward compatibility, line numbers can also follow a single -colon. - - -File: org.info, Node: Custom Searches, Prev: Search Options, Up: Hyperlinks - -4.9 Custom Searches -=================== - -The default mechanism for creating search strings and for doing the -actual search related to a file link may not work correctly in all -cases. For example, BibTeX database files have many entries like -‘year="1993"’ which would not result in good search strings, because the -only unique identification for a BibTeX entry is the citation key. - - If you come across such a problem, you can write custom functions to -set the right search string for a particular file type, and to do the -search for the string in the file. Using ‘add-hook’, these functions -need to be added to the hook variables -‘org-create-file-search-functions’ and -‘org-execute-file-search-functions’. See the docstring for these -variables for more information. Org actually uses this mechanism for -BibTeX database files, and you can use the corresponding code as an -implementation example. See the file ‘ol-bibtex.el’. - - -File: org.info, Node: TODO Items, Next: Tags, Prev: Hyperlinks, Up: Top - -5 TODO Items -************ - -Org mode does not maintain TODO lists as separate documents(1). -Instead, TODO items are an integral part of the notes file, because TODO -items usually come up while taking notes! With Org mode, simply mark -any entry in a tree as being a TODO item. In this way, information is -not duplicated, and the entire context from which the TODO item emerged -is always present. - - Of course, this technique for managing TODO items scatters them -throughout your notes file. Org mode compensates for this by providing -methods to give you an overview of all the things that you have to do. - -* Menu: - -* TODO Basics:: Marking and displaying TODO entries. -* TODO Extensions:: Workflow and assignments. -* Progress Logging:: Dates and notes for progress. -* Priorities:: Some things are more important than others. -* Breaking Down Tasks:: Splitting a task into manageable pieces. -* Checkboxes:: Tick-off lists. - - ---------- Footnotes ---------- - - (1) Of course, you can make a document that contains only long lists -of TODO items, but this is not required. - - -File: org.info, Node: TODO Basics, Next: TODO Extensions, Up: TODO Items - -5.1 Basic TODO Functionality -============================ - -Any headline becomes a TODO item when it starts with the word ‘TODO’, -for example: - - *** TODO Write letter to Sam Fortune - - The most important commands to work with TODO entries are: - -‘C-c C-t’ (‘org-todo’) - Rotate the TODO state of the current item among - - ,-> (unmarked) -> TODO -> DONE --. - '--------------------------------' - - If TODO keywords have fast access keys (see *note Fast access to - TODO states::), prompt for a TODO keyword through the fast - selection interface; this is the default behavior when - ‘org-use-fast-todo-selection’ is non-‘nil’. - - The same state changing can also be done “remotely” from the agenda - buffer with the ‘t’ command key (see *note Agenda Commands::). - -‘S-<RIGHT>’ ‘S-<LEFT>’ - Select the following/preceding TODO state, similar to cycling. - Useful mostly if more than two TODO states are possible (see *note - TODO Extensions::). See also *note Conflicts::, for a discussion - of the interaction with shift-selection. See also the variable - ‘org-treat-S-cursor-todo-selection-as-state-change’. - -‘C-c / t’ (‘org-show-todo-tree’) - View TODO items in a _sparse tree_ (see *note Sparse Trees::). - Folds the entire buffer, but shows all TODO items—with not-DONE - state—and the headings hierarchy above them. With a prefix - argument, or by using ‘C-c / T’, search for a specific TODO. You - are prompted for the keyword, and you can also give a list of - keywords like ‘KWD1|KWD2|...’ to list entries that match any one of - these keywords. With a numeric prefix argument N, show the tree - for the Nth keyword in the variable ‘org-todo-keywords’. With two - prefix arguments, find all TODO states, both un-done and done. - -‘M-x org-agenda t’ (‘org-todo-list’) - Show the global TODO list. Collects the TODO items (with not-DONE - states) from all agenda files (see *note Agenda Views::) into a - single buffer. The new buffer is in Org Agenda mode, which - provides commands to examine and manipulate the TODO entries from - the new buffer (see *note Agenda Commands::). See *note Global - TODO list::, for more information. - -‘S-M-<RET>’ (‘org-insert-todo-heading’) - Insert a new TODO entry below the current one. - - Changing a TODO state can also trigger tag changes. See the -docstring of the option ‘org-todo-state-tags-triggers’ for details. - - -File: org.info, Node: TODO Extensions, Next: Progress Logging, Prev: TODO Basics, Up: TODO Items - -5.2 Extended Use of TODO Keywords -================================= - -By default, marked TODO entries have one of only two states: TODO and -DONE. Org mode allows you to classify TODO items in more complex ways -with _TODO keywords_ (stored in ‘org-todo-keywords’). With special -setup, the TODO keyword system can work differently in different files. - - Note that _tags_ are another way to classify headlines in general and -TODO items in particular (see *note Tags::). - -* Menu: - -* Workflow states:: From TODO to DONE in steps. -* TODO types:: I do this, Fred does the rest. -* Multiple sets in one file:: Mixing it all, still finding your way. -* Fast access to TODO states:: Single letter selection of state. -* Per-file keywords:: Different files, different requirements. -* Faces for TODO keywords:: Highlighting states. -* TODO dependencies:: When one task needs to wait for others. - - -File: org.info, Node: Workflow states, Next: TODO types, Up: TODO Extensions - -5.2.1 TODO keywords as workflow states --------------------------------------- - -You can use TODO keywords to indicate different, possibly _sequential_ -states in the process of working on an item, for example(1): - - (setq org-todo-keywords - '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED"))) - - The vertical bar separates the TODO keywords (states that _need -action_) from the DONE states (which need _no further action_). If you -do not provide the separator bar, the last state is used as the DONE -state. - - With this setup, the command ‘C-c C-t’ cycles an entry from ‘TODO’ to -‘FEEDBACK’, then to ‘VERIFY’, and finally to ‘DONE’ and ‘DELEGATED’. -You may also use a numeric prefix argument to quickly select a specific -state. For example ‘C-3 C-c C-t’ changes the state immediately to -‘VERIFY’. Or you can use ‘S-<RIGHT>’ and ‘S-<LEFT>’ to go forward and -backward through the states. If you define many keywords, you can use -in-buffer completion (see *note Completion::) or a special one-key -selection scheme (see *note Fast access to TODO states::) to insert -these words into the buffer. Changing a TODO state can be logged with a -timestamp, see *note Tracking TODO state changes::, for more -information. - - ---------- Footnotes ---------- - - (1) Changing the variable ‘org-todo-keywords’ only becomes effective -after restarting Org mode in a buffer. - - -File: org.info, Node: TODO types, Next: Multiple sets in one file, Prev: Workflow states, Up: TODO Extensions - -5.2.2 TODO keywords as types ----------------------------- - -The second possibility is to use TODO keywords to indicate different -_types_ of action items. For example, you might want to indicate that -items are for “work” or “home”. Or, when you work with several people -on a single project, you might want to assign action items directly to -persons, by using their names as TODO keywords. This type of -functionality is actually much better served by using tags (see *note -Tags::), so the TODO implementation is kept just for backward -compatibility. - - Using TODO types, it would be set up like this: - - (setq org-todo-keywords '((type "Fred" "Sara" "Lucy" "|" "DONE"))) - - In this case, different keywords do not indicate states, but rather -different types. So the normal work flow would be to assign a task to a -person, and later to mark it DONE. Org mode supports this style by -adapting the workings of the command ‘C-c C-t’(1). When used several -times in succession, it still cycles through all names, in order to -first select the right type for a task. But when you return to the item -after some time and execute ‘C-c C-t’ again, it will switch from any -name directly to ‘DONE’. Use prefix arguments or completion to quickly -select a specific name. You can also review the items of a specific -TODO type in a sparse tree by using a numeric prefix to ‘C-c / t’. For -example, to see all things Lucy has to do, you would use ‘C-3 C-c / t’. -To collect Lucy’s items from all agenda files into a single buffer, you -would use the numeric prefix argument as well when creating the global -TODO list: ‘C-3 M-x org-agenda t’. - - ---------- Footnotes ---------- - - (1) This is also true for the ‘t’ command in the agenda buffer. - - -File: org.info, Node: Multiple sets in one file, Next: Fast access to TODO states, Prev: TODO types, Up: TODO Extensions - -5.2.3 Multiple keyword sets in one file ---------------------------------------- - -Sometimes you may want to use different sets of TODO keywords in -parallel. For example, you may want to have the basic TODO/DONE, but -also a workflow for bug fixing, and a separate state indicating that an -item has been canceled—so it is not DONE, but also does not require -action. Your setup would then look like this: - - (setq org-todo-keywords - '((sequence "TODO" "|" "DONE") - (sequence "REPORT" "BUG" "KNOWNCAUSE" "|" "FIXED") - (sequence "|" "CANCELED"))) - - The keywords should all be different, this helps Org mode keep track -of which subsequence should be used for a given entry. In this setup, -‘C-c C-t’ only operates within a sub-sequence, so it switches from -‘DONE’ to (nothing) to ‘TODO’, and from ‘FIXED’ to (nothing) to -‘REPORT’. Therefore you need a mechanism to initially select the -correct sequence. In addition to typing a keyword or using completion -(see *note Completion::), you may also apply the following commands: - -‘C-u C-u C-c C-t’ -‘C-S-<RIGHT>’ -‘C-S-<LEFT>’ - These keys jump from one TODO sub-sequence to the next. In the - above example, ‘C-u C-u C-c C-t’ or ‘C-S-<RIGHT>’ would jump from - ‘TODO’ or ‘DONE’ to ‘REPORT’, and any of the words in the second - row to ‘CANCELED’. Note that the ‘C-S-’ key binding conflict with - shift-selection (see *note Conflicts::). - -‘S-<RIGHT>’ -‘S-<LEFT>’ - ‘S-<LEFT>’ and ‘S-<RIGHT>’ walk through _all_ keywords from all - sub-sequences, so for example ‘S-<RIGHT>’ would switch from ‘DONE’ - to ‘REPORT’ in the example above. For a discussion of the - interaction with shift-selection, see *note Conflicts::. - - -File: org.info, Node: Fast access to TODO states, Next: Per-file keywords, Prev: Multiple sets in one file, Up: TODO Extensions - -5.2.4 Fast access to TODO states --------------------------------- - -If you would like to quickly change an entry to an arbitrary TODO state -instead of cycling through the states, you can set up keys for -single-letter access to the states. This is done by adding the -selection character after each keyword, in parentheses(1). For example: - - (setq org-todo-keywords - '((sequence "TODO(t)" "|" "DONE(d)") - (sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)") - (sequence "|" "CANCELED(c)"))) - - If you then press ‘C-c C-t’ followed by the selection key, the entry -is switched to this state. ‘<SPC>’ can be used to remove any TODO -keyword from an entry(2). - - ---------- Footnotes ---------- - - (1) All characters are allowed except ‘@’, ‘^’ and ‘!’, which have a -special meaning here. - - (2) Check also the variable ‘org-fast-tag-selection-include-todo’, it -allows you to change the TODO state through the tags interface (see -*note Setting Tags::), in case you like to mingle the two concepts. -Note that this means you need to come up with unique keys across both -sets of keywords. - - -File: org.info, Node: Per-file keywords, Next: Faces for TODO keywords, Prev: Fast access to TODO states, Up: TODO Extensions - -5.2.5 Setting up keywords for individual files ----------------------------------------------- - -It can be very useful to use different aspects of the TODO mechanism in -different files. For file-local settings, you need to add special lines -to the file which set the keywords and interpretation for that file -only. For example, to set one of the two examples discussed above, you -need one of the following lines, starting in column zero anywhere in the -file: - - #+TODO: TODO FEEDBACK VERIFY | DONE CANCELED - - You may also write ‘#+SEQ_TODO’ to be explicit about the -interpretation, but it means the same as ‘#+TODO’, or - - #+TYP_TODO: Fred Sara Lucy Mike | DONE - - A setup for using several sets in parallel would be: - - #+TODO: TODO(t) | DONE(d) - #+TODO: REPORT(r) BUG(b) KNOWNCAUSE(k) | FIXED(f) - #+TODO: | CANCELED(c) - - To make sure you are using the correct keyword, type ‘#+’ into the -buffer and then use ‘M-<TAB>’ to complete it (see *note Completion::). - - Remember that the keywords after the vertical bar—or the last keyword -if no bar is there—must always mean that the item is DONE, although you -may use a different word. After changing one of these lines, use ‘C-c -C-c’ with point still in the line to make the changes known to Org -mode(1). - - ---------- Footnotes ---------- - - (1) Org mode parses these lines only when Org mode is activated after -visiting a file. ‘C-c C-c’ with point in a line starting with ‘#+’ is -simply restarting Org mode for the current buffer. - - -File: org.info, Node: Faces for TODO keywords, Next: TODO dependencies, Prev: Per-file keywords, Up: TODO Extensions - -5.2.6 Faces for TODO keywords ------------------------------ - -Org mode highlights TODO keywords with special faces: ‘org-todo’ for -keywords indicating that an item still has to be acted upon, and -‘org-done’ for keywords indicating that an item is finished. If you are -using more than two different states, you might want to use special -faces for some of them. This can be done using the variable -‘org-todo-keyword-faces’. For example: - - (setq org-todo-keyword-faces - '(("TODO" . org-warning) ("STARTED" . "yellow") - ("CANCELED" . (:foreground "blue" :weight bold)))) - - While using a list with face properties as shown for ‘CANCELED’ -_should_ work, this does not always seem to be the case. If necessary, -define a special face and use that. A string is interpreted as a color. -The variable ‘org-faces-easy-properties’ determines if that color is -interpreted as a foreground or a background color. - - -File: org.info, Node: TODO dependencies, Prev: Faces for TODO keywords, Up: TODO Extensions - -5.2.7 TODO dependencies ------------------------ - -The structure of Org files—hierarchy and lists—makes it easy to define -TODO dependencies. Usually, a parent TODO task should not be marked as -done until all TODO subtasks, or children tasks, are marked as done. -Sometimes there is a logical sequence to (sub)tasks, so that one subtask -cannot be acted upon before all siblings above it have been marked as -done. If you customize the variable ‘org-enforce-todo-dependencies’, -Org blocks entries from changing state to DONE while they have TODO -children that are not DONE. Furthermore, if an entry has a property -‘ORDERED’, each of its TODO children is blocked until all earlier -siblings are marked as done. Here is an example: - - * TODO Blocked until (two) is done - ** DONE one - ** TODO two - - * Parent - :PROPERTIES: - :ORDERED: t - :END: - ** TODO a - ** TODO b, needs to wait for (a) - ** TODO c, needs to wait for (a) and (b) - - You can ensure an entry is never blocked by using the ‘NOBLOCKING’ -property (see *note Properties and Columns::): - - * This entry is never blocked - :PROPERTIES: - :NOBLOCKING: t - :END: - -‘C-c C-x o’ (‘org-toggle-ordered-property’) - Toggle the ‘ORDERED’ property of the current entry. A property is - used for this behavior because this should be local to the current - entry, not inherited from entries above like a tag (see *note - Tags::). However, if you would like to _track_ the value of this - property with a tag for better visibility, customize the variable - ‘org-track-ordered-property-with-tag’. - -‘C-u C-u C-u C-c C-t’ - Change TODO state, regardless of any state blocking. - - If you set the variable ‘org-agenda-dim-blocked-tasks’, TODO entries -that cannot be marked as done because of unmarked children are shown in -a dimmed font or even made invisible in agenda views (see *note Agenda -Views::). - - You can also block changes of TODO states by using checkboxes (see -*note Checkboxes::). If you set the variable -‘org-enforce-todo-checkbox-dependencies’, an entry that has unchecked -checkboxes is blocked from switching to DONE. - - If you need more complex dependency structures, for example -dependencies between entries in different trees or files, check out the -module ‘org-depend.el’ in the ‘org-contrib’ repository. - - -File: org.info, Node: Progress Logging, Next: Priorities, Prev: TODO Extensions, Up: TODO Items - -5.3 Progress Logging -==================== - -To record a timestamp and a note when changing a TODO state, call the -command ‘org-todo’ with a prefix argument. - -‘C-u C-c C-t’ (‘org-todo’) - Prompt for a note and record a the time of the TODO state change. - The note is inserted as a list item below the headline, but can - also be placed into a drawer, see *note Tracking TODO state - changes::. - - If you want to be more systematic, Org mode can automatically record -a timestamp and optionally a note when you mark a TODO item as DONE, or -even each time you change the state of a TODO item. This system is -highly configurable, settings can be on a per-keyword basis and can be -localized to a file or even a subtree. For information on how to clock -working time for a task, see *note Clocking Work Time::. - -* Menu: - -* Closing items:: When was this entry marked as done? -* Tracking TODO state changes:: When did the status change? -* Tracking your habits:: How consistent have you been? - - -File: org.info, Node: Closing items, Next: Tracking TODO state changes, Up: Progress Logging - -5.3.1 Closing items -------------------- - -The most basic automatic logging is to keep track of _when_ a certain -TODO item was marked as done. This can be achieved with(1) - - (setq org-log-done 'time) - -Then each time you turn an entry from a TODO (not-done) state into any -of the DONE states, a line ‘CLOSED: [timestamp]’ is inserted just after -the headline. If you turn the entry back into a TODO item through -further state cycling, that line is removed again. If you turn the -entry back to a non-TODO state (by pressing ‘C-c C-t <SPC>’ for -example), that line is also removed, unless you set -‘org-closed-keep-when-no-todo’ to non-‘nil’. If you want to record a -note along with the timestamp, use(2) - - (setq org-log-done 'note) - -You are then prompted for a note, and that note is stored below the -entry with a ‘Closing Note’ heading. - - ---------- Footnotes ---------- - - (1) The corresponding in-buffer setting is: ‘#+STARTUP: logdone’. - - (2) The corresponding in-buffer setting is: ‘#+STARTUP: lognotedone’. - - -File: org.info, Node: Tracking TODO state changes, Next: Tracking your habits, Prev: Closing items, Up: Progress Logging - -5.3.2 Tracking TODO state changes ---------------------------------- - -You might want to automatically keep track of when a state change -occurred and maybe take a note about this change. You can either record -just a timestamp, or a time-stamped note. These records are inserted -after the headline as an itemized list, newest first(1). When taking a -lot of notes, you might want to get the notes out of the way into a -drawer (see *note Drawers::). Customize the variable -‘org-log-into-drawer’ to get this behavior—the recommended drawer for -this is called ‘LOGBOOK’(2). You can also overrule the setting of this -variable for a subtree by setting a ‘LOG_INTO_DRAWER’ property. - - Since it is normally too much to record a note for every state, Org -mode expects configuration on a per-keyword basis for this. This is -achieved by adding special markers ‘!’ (for a timestamp) or ‘@’ (for a -note with timestamp) in parentheses after each keyword. For example, -with the setting - - (setq org-todo-keywords - '((sequence "TODO(t)" "WAIT(w@/!)" "|" "DONE(d!)" "CANCELED(c@)"))) - - You not only define global TODO keywords and fast access keys, but -also request that a time is recorded when the entry is set to ‘DONE’, -and that a note is recorded when switching to ‘WAIT’ or ‘CANCELED’(3). -The setting for ‘WAIT’ is even more special: the ‘!’ after the slash -means that in addition to the note taken when entering the state, a -timestamp should be recorded when _leaving_ the ‘WAIT’ state, if and -only if the _target_ state does not configure logging for entering it. -So it has no effect when switching from ‘WAIT’ to ‘DONE’, because ‘DONE’ -is configured to record a timestamp only. But when switching from -‘WAIT’ back to ‘TODO’, the ‘/!’ in the ‘WAIT’ setting now triggers a -timestamp even though ‘TODO’ has no logging configured. - - You can use the exact same syntax for setting logging preferences -local to a buffer: - - #+TODO: TODO(t) WAIT(w@/!) | DONE(d!) CANCELED(c@) - - To record a timestamp without a note for TODO keywords configured -with ‘@’, just type ‘C-c C-c’ to enter a blank note when prompted. - - In order to define logging settings that are local to a subtree or a -single item, define a ‘LOGGING’ property in this entry. Any non-empty -‘LOGGING’ property resets all logging settings to ‘nil’. You may then -turn on logging for this specific tree using ‘STARTUP’ keywords like -‘lognotedone’ or ‘logrepeat’, as well as adding state specific settings -like ‘TODO(!)’. For example: - - * TODO Log each state with only a time - :PROPERTIES: - :LOGGING: TODO(!) WAIT(!) DONE(!) CANCELED(!) - :END: - * TODO Only log when switching to WAIT, and when repeating - :PROPERTIES: - :LOGGING: WAIT(@) logrepeat - :END: - * TODO No logging at all - :PROPERTIES: - :LOGGING: nil - :END: - - ---------- Footnotes ---------- - - (1) See the variable ‘org-log-states-order-reversed’. - - (2) Note that the ‘LOGBOOK’ drawer is unfolded when pressing ‘<SPC>’ -in the agenda to show an entry—use ‘C-u <SPC>’ to keep it folded here. - - (3) It is possible that Org mode records two timestamps when you are -using both ‘org-log-done’ and state change logging. However, it never -prompts for two notes: if you have configured both, the state change -recording note takes precedence and cancel the closing note. - - -File: org.info, Node: Tracking your habits, Prev: Tracking TODO state changes, Up: Progress Logging - -5.3.3 Tracking your habits --------------------------- - -Org has the ability to track the consistency of a special category of -TODO, called “habits.” To use habits, you have to enable the ‘habits’ -module by customizing the variable ‘org-modules’. - - A habit has the following properties: - - 1. The habit is a TODO item, with a TODO keyword representing an open - state. - - 2. The property ‘STYLE’ is set to the value ‘habit’ (see *note - Properties and Columns::). - - 3. The TODO has a scheduled date, usually with a ‘.+’ style repeat - interval. A ‘++’ style may be appropriate for habits with time - constraints, e.g., must be done on weekends, or a ‘+’ style for an - unusual habit that can have a backlog, e.g., weekly reports. - - 4. The TODO may also have minimum and maximum ranges specified by - using the syntax ‘.+2d/3d’, which says that you want to do the task - at least every three days, but at most every two days. - - 5. State logging for the DONE state is enabled (see *note Tracking - TODO state changes::), in order for historical data to be - represented in the consistency graph. If it is not enabled it is - not an error, but the consistency graphs are largely meaningless. - - To give you an idea of what the above rules look like in action, -here’s an actual habit with some history: - - ** TODO Shave - SCHEDULED: <2009-10-17 Sat .+2d/4d> - :PROPERTIES: - :STYLE: habit - :LAST_REPEAT: [2009-10-19 Mon 00:36] - :END: - - State "DONE" from "TODO" [2009-10-15 Thu] - - State "DONE" from "TODO" [2009-10-12 Mon] - - State "DONE" from "TODO" [2009-10-10 Sat] - - State "DONE" from "TODO" [2009-10-04 Sun] - - State "DONE" from "TODO" [2009-10-02 Fri] - - State "DONE" from "TODO" [2009-09-29 Tue] - - State "DONE" from "TODO" [2009-09-25 Fri] - - State "DONE" from "TODO" [2009-09-19 Sat] - - State "DONE" from "TODO" [2009-09-16 Wed] - - State "DONE" from "TODO" [2009-09-12 Sat] - - What this habit says is: I want to shave at most every 2 days—given -by the ‘SCHEDULED’ date and repeat interval—and at least every 4 days. -If today is the 15th, then the habit first appears in the agenda (see -*note Agenda Views::) on Oct 17, after the minimum of 2 days has -elapsed, and will appear overdue on Oct 19, after four days have -elapsed. - - What’s really useful about habits is that they are displayed along -with a consistency graph, to show how consistent you’ve been at getting -that task done in the past. This graph shows every day that the task -was done over the past three weeks, with colors for each day. The -colors used are: - -Blue - If the task was not to be done yet on that day. -Green - If the task could have been done on that day. -Yellow - If the task was going to be overdue the next day. -Red - If the task was overdue on that day. - - In addition to coloring each day, the day is also marked with an -asterisk if the task was actually done that day, and an exclamation mark -to show where the current day falls in the graph. - - There are several configuration variables that can be used to change -the way habits are displayed in the agenda. - -‘org-habit-graph-column’ - The buffer column at which the consistency graph should be drawn. - This overwrites any text in that column, so it is a good idea to - keep your habits’ titles brief and to the point. - -‘org-habit-preceding-days’ - The amount of history, in days before today, to appear in - consistency graphs. - -‘org-habit-following-days’ - The number of days after today that appear in consistency graphs. - -‘org-habit-show-habits-only-for-today’ - If non-‘nil’, only show habits in today’s agenda view. The default - value is ‘t’. Pressing ‘C-u K’ in the agenda toggles this - variable. - - Lastly, pressing ‘K’ in the agenda buffer causes habits to -temporarily be disabled and do not appear at all. Press ‘K’ again to -bring them back. They are also subject to tag filtering, if you have -habits which should only be done in certain contexts, for example. - - -File: org.info, Node: Priorities, Next: Breaking Down Tasks, Prev: Progress Logging, Up: TODO Items - -5.4 Priorities -============== - -If you use Org mode extensively, you may end up with enough TODO items -that it starts to make sense to prioritize them. Prioritizing can be -done by placing a _priority cookie_ into the headline of a TODO item -right after the TODO keyword, like this: - - *** TODO [#A] Write letter to Sam Fortune - - By default, Org mode supports three priorities: ‘A’, ‘B’, and ‘C’. -‘A’ is the highest priority. An entry without a cookie is treated as -equivalent if it had priority ‘B’. Priorities make a difference only -for sorting in the agenda (see *note Weekly/daily agenda::). Outside -the agenda, they have no inherent meaning to Org mode. The cookies are -displayed with the face defined by the variable ‘org-priority-faces’, -which can be customized. - - You can also use numeric values for priorities, such as - - *** TODO [#1] Write letter to Sam Fortune - - When using numeric priorities, you need to set -‘org-priority-highest’, ‘org-priority-lowest’ and ‘org-priority-default’ -to integers, which must all be strictly inferior to 65. - - Priorities can be attached to any outline node; they do not need to -be TODO items. - -‘C-c ,’ (‘org-priority’) - Set the priority of the current headline. The command prompts for - a priority character ‘A’, ‘B’ or ‘C’. When you press ‘<SPC>’ - instead, the priority cookie, if one is set, is removed from the - headline. The priorities can also be changed “remotely” from the - agenda buffer with the ‘,’ command (see *note Agenda Commands::). - -‘S-<UP>’ (‘org-priority-up’) -‘S-<DOWN>’ (‘org-priority-down’) - Increase/decrease the priority of the current headline(1). Note - that these keys are also used to modify timestamps (see *note - Creating Timestamps::). See also *note Conflicts::, for a - discussion of the interaction with shift-selection. - - You can change the range of allowed priorities by setting the -variables ‘org-priority-highest’, ‘org-priority-lowest’, and -‘org-priority-default’. For an individual buffer, you may set these -values (highest, lowest, default) like this (please make sure that the -highest priority is earlier in the alphabet than the lowest priority): - - #+PRIORITIES: A C B - - Or, using numeric values: - - #+PRIORITIES: 1 10 5 - - ---------- Footnotes ---------- - - (1) See also the option ‘org-priority-start-cycle-with-default’. - - -File: org.info, Node: Breaking Down Tasks, Next: Checkboxes, Prev: Priorities, Up: TODO Items - -5.5 Breaking Down Tasks into Subtasks -===================================== - -It is often advisable to break down large tasks into smaller, manageable -subtasks. You can do this by creating an outline tree below a TODO -item, with detailed subtasks on the tree(1). To keep an overview of the -fraction of subtasks that have already been marked as done, insert -either ‘[/]’ or ‘[%]’ anywhere in the headline. These cookies are -updated each time the TODO status of a child changes, or when pressing -‘C-c C-c’ on the cookie. For example: - - * Organize Party [33%] - ** TODO Call people [1/2] - *** TODO Peter - *** DONE Sarah - ** TODO Buy food - ** DONE Talk to neighbor - - If a heading has both checkboxes and TODO children below it, the -meaning of the statistics cookie become ambiguous. Set the property -‘COOKIE_DATA’ to either ‘checkbox’ or ‘todo’ to resolve this issue. - - If you would like to have the statistics cookie count any TODO -entries in the subtree (not just direct children), configure the -variable ‘org-hierarchical-todo-statistics’. To do this for a single -subtree, include the word ‘recursive’ into the value of the -‘COOKIE_DATA’ property. - - * Parent capturing statistics [2/20] - :PROPERTIES: - :COOKIE_DATA: todo recursive - :END: - - If you would like a TODO entry to automatically change to DONE when -all children are done, you can use the following setup: - - (defun org-summary-todo (n-done n-not-done) - "Switch entry to DONE when all subentries are done, to TODO otherwise." - (let (org-log-done org-log-states) ; turn off logging - (org-todo (if (= n-not-done 0) "DONE" "TODO")))) - - (add-hook 'org-after-todo-statistics-hook #'org-summary-todo) - - Another possibility is the use of checkboxes to identify (a hierarchy -of) a large number of subtasks (see *note Checkboxes::). - - ---------- Footnotes ---------- - - (1) To keep subtasks out of the global TODO list, see the option -‘org-agenda-todo-list-sublevels’. - - -File: org.info, Node: Checkboxes, Prev: Breaking Down Tasks, Up: TODO Items - -5.6 Checkboxes -============== - -Every item in a plain list(1) (see *note Plain Lists::) can be made into -a checkbox by starting it with the string ‘[ ]’. This feature is -similar to TODO items (see *note TODO Items::), but is more lightweight. -Checkboxes are not included into the global TODO list, so they are often -great to split a task into a number of simple steps. Or you can use -them in a shopping list. - - Here is an example of a checkbox list. - - * TODO Organize party [2/4] - - [-] call people [1/3] - - [ ] Peter - - [X] Sarah - - [ ] Sam - - [X] order food - - [ ] think about what music to play - - [X] talk to the neighbors - - Checkboxes work hierarchically, so if a checkbox item has children -that are checkboxes, toggling one of the children checkboxes makes the -parent checkbox reflect if none, some, or all of the children are -checked. - - The ‘[2/4]’ and ‘[1/3]’ in the first and second line are cookies -indicating how many checkboxes present in this entry have been checked -off, and the total number of checkboxes present. This can give you an -idea on how many checkboxes remain, even without opening a folded entry. -The cookies can be placed into a headline or into (the first line of) a -plain list item. Each cookie covers checkboxes of direct children -structurally below the headline/item on which the cookie appears(2). -You have to insert the cookie yourself by typing either ‘[/]’ or ‘[%]’. -With ‘[/]’ you get an ‘n out of m’ result, as in the examples above. -With ‘[%]’ you get information about the percentage of checkboxes -checked (in the above example, this would be ‘[50%]’ and ‘[33%]’, -respectively). In a headline, a cookie can count either checkboxes -below the heading or TODO states of children, and it displays whatever -was changed last. Set the property ‘COOKIE_DATA’ to either ‘checkbox’ -or ‘todo’ to resolve this issue. - - If the current outline node has an ‘ORDERED’ property, checkboxes -must be checked off in sequence, and an error is thrown if you try to -check off a box while there are unchecked boxes above it. - - The following commands work with checkboxes: - -‘C-c C-c’ (‘org-toggle-checkbox’) - Toggle checkbox status or—with prefix argument—checkbox presence at - point. With a single prefix argument, add an empty checkbox or - remove the current one(3). With a double prefix argument, set it - to ‘[-]’, which is considered to be an intermediate state. - -‘C-c C-x C-b’ (‘org-toggle-checkbox’) - Toggle checkbox status or—with prefix argument—checkbox presence at - point. With double prefix argument, set it to ‘[-]’, which is - considered to be an intermediate state. - - • If there is an active region, toggle the first checkbox in the - region and set all remaining boxes to the same status as the - first. With a prefix argument, add or remove the checkbox for - all items in the region. - - • If point is in a headline, toggle checkboxes in the region - between this headline and the next—so _not_ the entire - subtree. - - • If there is no active region, just toggle the checkbox at - point. - -‘C-c C-x C-r’ (‘org-toggle-radio-button’) - Toggle checkbox status by using the checkbox of the item at point - as a radio button: when the checkbox is turned on, all other - checkboxes on the same level will be turned off. With a universal - prefix argument, toggle the presence of the checkbox. With a - double prefix argument, set it to ‘[-]’. - - ‘C-c C-c’ can be told to consider checkboxes as radio buttons by - setting ‘#+ATTR_ORG: :radio t’ right before the list or by calling - ‘M-x org-list-checkbox-radio-mode’ to activate this minor mode. - -‘M-S-<RET>’ (‘org-insert-todo-heading’) - Insert a new item with a checkbox. This works only if point is - already in a plain list item (see *note Plain Lists::). - -‘C-c C-x o’ (‘org-toggle-ordered-property’) - Toggle the ‘ORDERED’ property of the entry, to toggle if checkboxes - must be checked off in sequence. A property is used for this - behavior because this should be local to the current entry, not - inherited like a tag. However, if you would like to _track_ the - value of this property with a tag for better visibility, customize - ‘org-track-ordered-property-with-tag’. - -‘C-c #’ (‘org-update-statistics-cookies’) - Update the statistics cookie in the current outline entry. When - called with a ‘C-u’ prefix, update the entire file. Checkbox - statistic cookies are updated automatically if you toggle - checkboxes with ‘C-c C-c’ and make new ones with ‘M-S-<RET>’. TODO - statistics cookies update when changing TODO states. If you delete - boxes/entries or add/change them by hand, use this command to get - things back into sync. - - ---------- Footnotes ---------- - - (1) With the exception of description lists. But you can allow it by -modifying ‘org-list-automatic-rules’ accordingly. - - (2) Set the variable ‘org-hierarchical-checkbox-statistics’ if you -want such cookies to count all checkboxes below the cookie, not just -those belonging to direct children. - - (3) ‘C-u C-c C-c’ on the _first_ item of a list with no checkbox adds -checkboxes to the rest of the list. - - -File: org.info, Node: Tags, Next: Properties and Columns, Prev: TODO Items, Up: Top - -6 Tags -****** - -An excellent way to implement labels and contexts for cross-correlating -information is to assign _tags_ to headlines. Org mode has extensive -support for tags. - - Every headline can contain a list of tags; they occur at the end of -the headline. Tags are normal words containing letters, numbers, ‘_’, -and ‘@’. Tags must be preceded and followed by a single colon, e.g., -‘:work:’. Several tags can be specified, as in ‘:work:urgent:’. Tags -by default are in bold face with the same color as the headline. You -may specify special faces for specific tags using the variable -‘org-tag-faces’, in much the same way as you can for TODO keywords (see -*note Faces for TODO keywords::). - -* Menu: - -* Tag Inheritance:: Tags use the tree structure of an outline. -* Setting Tags:: How to assign tags to a headline. -* Tag Hierarchy:: Create a hierarchy of tags. -* Tag Searches:: Searching for combinations of tags. - - -File: org.info, Node: Tag Inheritance, Next: Setting Tags, Up: Tags - -6.1 Tag Inheritance -=================== - -_Tags_ make use of the hierarchical structure of outline trees. If a -heading has a certain tag, all subheadings inherit the tag as well. For -example, in the list - - * Meeting with the French group :work: - ** Summary by Frank :boss:notes: - *** TODO Prepare slides for him :action: - -the final heading has the tags ‘work’, ‘boss’, ‘notes’, and ‘action’ -even though the final heading is not explicitly marked with those tags. -You can also set tags that all entries in a file should inherit just as -if these tags were defined in a hypothetical level zero that surrounds -the entire file. Use a line like this(1) - - #+FILETAGS: :Peter:Boss:Secret: - - To limit tag inheritance to specific tags, or to turn it off -entirely, use the variables ‘org-use-tag-inheritance’ and -‘org-tags-exclude-from-inheritance’. - - When a headline matches during a tags search while tag inheritance is -turned on, all the sublevels in the same tree—for a simple match -form—match as well(2). The list of matches may then become very long. -If you only want to see the first tags match in a subtree, configure the -variable ‘org-tags-match-list-sublevels’ (not recommended). - - Tag inheritance is relevant when the agenda search tries to match a -tag, either in the ‘tags’ or ‘tags-todo’ agenda types. In other agenda -types, ‘org-use-tag-inheritance’ has no effect. Still, you may want to -have your tags correctly set in the agenda, so that tag filtering works -fine, with inherited tags. Set ‘org-agenda-use-tag-inheritance’ to -control this: the default value includes all agenda types, but setting -this to ‘nil’ can really speed up agenda generation. - - ---------- Footnotes ---------- - - (1) As with all these in-buffer settings, pressing ‘C-c C-c’ -activates any changes in the line. - - (2) This is only true if the search does not involve more complex -tests including properties (see *note Property Searches::). - - -File: org.info, Node: Setting Tags, Next: Tag Hierarchy, Prev: Tag Inheritance, Up: Tags - -6.2 Setting Tags -================ - -Tags can simply be typed into the buffer at the end of a headline. -After a colon, ‘M-<TAB>’ offers completion on tags. There is also a -special command for inserting tags: - -‘C-c C-q’ (‘org-set-tags-command’) - Enter new tags for the current headline. Org mode either offers - completion or a special single-key interface for setting tags, see - below. After pressing ‘<RET>’, the tags are inserted and aligned - to ‘org-tags-column’. When called with a ‘C-u’ prefix, all tags in - the current buffer are aligned to that column, just to make things - look nice. Tags are automatically realigned after promotion, - demotion, and TODO state changes (see *note TODO Basics::). - -‘C-c C-c’ (‘org-set-tags-command’) - When point is in a headline, this does the same as ‘C-c C-q’. - - Org supports tag insertion based on a _list of tags_. By default -this list is constructed dynamically, containing all tags currently used -in the buffer(1). You may also globally specify a hard list of tags -with the variable ‘org-tag-alist’. Finally you can set the default tags -for a given file using the ‘TAGS’ keyword, like - - #+TAGS: @work @home @tennisclub - #+TAGS: laptop car pc sailboat - - If you have globally defined your preferred set of tags using the -variable ‘org-tag-alist’, but would like to use a dynamic tag list in a -specific file, add an empty ‘TAGS’ keyword to that file: - - #+TAGS: - - If you have a preferred set of tags that you would like to use in -every file, in addition to those defined on a per-file basis by ‘TAGS’ -keyword, then you may specify a list of tags with the variable -‘org-tag-persistent-alist’. You may turn this off on a per-file basis -by adding a ‘STARTUP’ keyword to that file: - - #+STARTUP: noptag - - By default Org mode uses the standard minibuffer completion -facilities for entering tags. However, it also implements another, -quicker, tag selection method called _fast tag selection_. This allows -you to select and deselect tags with just a single key press. For this -to work well you should assign unique letters to most of your commonly -used tags. You can do this globally by configuring the variable -‘org-tag-alist’ in your Emacs init file. For example, you may find the -need to tag many items in different files with ‘@home’. In this case -you can set something like: - - (setq org-tag-alist '(("@work" . ?w) ("@home" . ?h) ("laptop" . ?l))) - - If the tag is only relevant to the file you are working on, then you -can instead set the ‘TAGS’ keyword as: - - #+TAGS: @work(w) @home(h) @tennisclub(t) laptop(l) pc(p) - - The tags interface shows the available tags in a splash window. If -you want to start a new line after a specific tag, insert ‘\n’ into the -tag list - - #+TAGS: @work(w) @home(h) @tennisclub(t) \n laptop(l) pc(p) - -or write them in two lines: - - #+TAGS: @work(w) @home(h) @tennisclub(t) - #+TAGS: laptop(l) pc(p) - - You can also group together tags that are mutually exclusive by using -braces, as in: - - #+TAGS: { @work(w) @home(h) @tennisclub(t) } laptop(l) pc(p) - -you indicate that at most one of ‘@work’, ‘@home’, and ‘@tennisclub’ -should be selected. Multiple such groups are allowed. - - Do not forget to press ‘C-c C-c’ with point in one of these lines to -activate any changes. - - To set these mutually exclusive groups in the variable -‘org-tags-alist’, you must use the dummy tags ‘:startgroup’ and -‘:endgroup’ instead of the braces. Similarly, you can use ‘:newline’ to -indicate a line break. The previous example would be set globally by -the following configuration: - - (setq org-tag-alist '((:startgroup . nil) - ("@work" . ?w) ("@home" . ?h) - ("@tennisclub" . ?t) - (:endgroup . nil) - ("laptop" . ?l) ("pc" . ?p))) - - If at least one tag has a selection key then pressing ‘C-c C-c’ -automatically presents you with a special interface, listing inherited -tags, the tags of the current headline, and a list of all valid tags -with corresponding keys(2). - - Pressing keys assigned to tags adds or removes them from the list of -tags in the current line. Selecting a tag in a group of mutually -exclusive tags turns off any other tag from that group. - - In this interface, you can also use the following special keys: - -‘<TAB>’ - Enter a tag in the minibuffer, even if the tag is not in the - predefined list. You can complete on all tags present in the - buffer and globally pre-defined tags from ‘org-tag-alist’ and - ‘org-tag-persistent-alist’. You can also add several tags: just - separate them with a comma. - -‘<SPC>’ - Clear all tags for this line. - -‘<RET>’ - Accept the modified set. - -‘C-g’ - Abort without installing changes. - -‘q’ - If ‘q’ is not assigned to a tag, it aborts like ‘C-g’. - -‘!’ - Turn off groups of mutually exclusive tags. Use this to (as an - exception) assign several tags from such a group. - -‘C-c’ - Toggle auto-exit after the next change (see below). If you are - using expert mode, the first ‘C-c’ displays the selection window. - - This method lets you assign tags to a headline with very few keys. -With the above setup, you could clear the current tags and set ‘@home’, -‘laptop’ and ‘pc’ tags with just the following keys: ‘C-c C-c <SPC> h l -p <RET>’. Switching from ‘@home’ to ‘@work’ would be done with ‘C-c C-c -w <RET>’ or alternatively with ‘C-c C-c C-c w’. Adding the -non-predefined tag ‘sarah’ could be done with ‘C-c C-c <TAB> s a r a h -<RET>’. - - If you find that most of the time you need only a single key press to -modify your list of tags, set the variable -‘org-fast-tag-selection-single-key’. Then you no longer have to press -‘<RET>’ to exit fast tag selection—it exits after the first change. If -you then occasionally need more keys, press ‘C-c’ to turn off auto-exit -for the current tag selection process (in effect: start selection with -‘C-c C-c C-c’ instead of ‘C-c C-c’). If you set the variable to the -value ‘expert’, the special window is not even shown for single-key tag -selection, it comes up only when you press an extra ‘C-c’. - - ---------- Footnotes ---------- - - (1) To extend this default list to all tags used in all agenda files -(see *note Agenda Views::), customize the variable -‘org-complete-tags-always-offer-all-agenda-tags’. - - (2) Keys are automatically assigned to tags that have no configured -keys. - - -File: org.info, Node: Tag Hierarchy, Next: Tag Searches, Prev: Setting Tags, Up: Tags - -6.3 Tag Hierarchy -================= - -Tags can be defined in hierarchies. A tag can be defined as a _group -tag_ for a set of other tags. The group tag can be seen as the “broader -term” for its set of tags. Defining multiple group tags and nesting -them creates a tag hierarchy. - - One use-case is to create a taxonomy of terms (tags) that can be used -to classify nodes in a document or set of documents. - - When you search for a group tag, it return matches for all members in -the group and its subgroups. In an agenda view, filtering by a group -tag displays or hide headlines tagged with at least one of the members -of the group or any of its subgroups. This makes tag searches and -filters even more flexible. - - You can set group tags by using brackets and inserting a colon -between the group tag and its related tags—beware that all whitespaces -are mandatory so that Org can parse this line correctly: - - #+TAGS: [ GTD : Control Persp ] - - In this example, ‘GTD’ is the group tag and it is related to two -other tags: ‘Control’, ‘Persp’. Defining ‘Control’ and ‘Persp’ as group -tags creates a hierarchy of tags: - - #+TAGS: [ Control : Context Task ] - #+TAGS: [ Persp : Vision Goal AOF Project ] - - That can conceptually be seen as a hierarchy of tags: - - • ‘GTD’ - • ‘Persp’ - • ‘Vision’ - • ‘Goal’ - • ‘AOF’ - • ‘Project’ - • ‘Control’ - • ‘Context’ - • ‘Task’ - - You can use the ‘:startgrouptag’, ‘:grouptags’ and ‘:endgrouptag’ -keyword directly when setting ‘org-tag-alist’ directly: - - (setq org-tag-alist '((:startgrouptag) - ("GTD") - (:grouptags) - ("Control") - ("Persp") - (:endgrouptag) - (:startgrouptag) - ("Control") - (:grouptags) - ("Context") - ("Task") - (:endgrouptag))) - - The tags in a group can be mutually exclusive if using the same group -syntax as is used for grouping mutually exclusive tags together; using -curly brackets. - - #+TAGS: { Context : @Home @Work @Call } - - When setting ‘org-tag-alist’ you can use ‘:startgroup’ and -‘:endgroup’ instead of ‘:startgrouptag’ and ‘:endgrouptag’ to make the -tags mutually exclusive. - - Furthermore, the members of a group tag can also be regular -expressions, creating the possibility of a more dynamic and rule-based -tag structure (see *note Regular Expressions::). The regular -expressions in the group must be specified within curly brackets. Here -is an expanded example: - - #+TAGS: [ Vision : {V@.+} ] - #+TAGS: [ Goal : {G@.+} ] - #+TAGS: [ AOF : {AOF@.+} ] - #+TAGS: [ Project : {P@.+} ] - - Searching for the tag ‘Project’ now lists all tags also including -regular expression matches for ‘P@.+’, and similarly for tag searches on -‘Vision’, ‘Goal’ and ‘AOF’. For example, this would work well for a -project tagged with a common project-identifier, e.g., ‘P@2014_OrgTags’. - - If you want to ignore group tags temporarily, toggle group tags -support with ‘org-toggle-tags-groups’, bound to ‘C-c C-x q’. If you -want to disable tag groups completely, set ‘org-group-tags’ to ‘nil’. - - -File: org.info, Node: Tag Searches, Prev: Tag Hierarchy, Up: Tags - -6.4 Tag Searches -================ - -Once a system of tags has been set up, it can be used to collect related -information into special lists. - -‘C-c / m’ or ‘C-c \’ (‘org-match-sparse-tree’) - Create a sparse tree with all headlines matching a tags search. - With a ‘C-u’ prefix argument, ignore headlines that are not a TODO - line. - -‘M-x org-agenda m’ (‘org-tags-view’) - Create a global list of tag matches from all agenda files. See - *note Matching tags and properties::. - -‘M-x org-agenda M’ (‘org-tags-view’) - Create a global list of tag matches from all agenda files, but - check only TODO items and force checking subitems (see the option - ‘org-tags-match-list-sublevels’). - - These commands all prompt for a match string which allows basic -Boolean logic like ‘+boss+urgent-project1’, to find entries with tags -‘boss’ and ‘urgent’, but not ‘project1’, or ‘Kathy|Sally’ to find -entries which are tagged, like ‘Kathy’ or ‘Sally’. The full syntax of -the search string is rich and allows also matching against TODO -keywords, entry levels and properties. For a complete description with -many examples, see *note Matching tags and properties::. - - -File: org.info, Node: Properties and Columns, Next: Dates and Times, Prev: Tags, Up: Top - -7 Properties and Columns -************************ - -A property is a key-value pair associated with an entry. Properties can -be set so they are associated with a single entry, with every entry in a -tree, or with the whole buffer. - - There are two main applications for properties in Org mode. First, -properties are like tags, but with a value. Imagine maintaining a file -where you document bugs and plan releases for a piece of software. -Instead of using tags like ‘release_1’, ‘release_2’, you can use a -property, say ‘Release’, that in different subtrees has different -values, such as ‘1.0’ or ‘2.0’. Second, you can use properties to -implement (very basic) database capabilities in an Org buffer. Imagine -keeping track of your music CDs, where properties could be things such -as the album, artist, date of release, number of tracks, and so on. - - Properties can be conveniently edited and viewed in column view (see -*note Column View::). - -* Menu: - -* Property Syntax:: How properties are spelled out. -* Special Properties:: Access to other Org mode features. -* Property Searches:: Matching property values. -* Property Inheritance:: Passing values down a tree. -* Column View:: Tabular viewing and editing. - - -File: org.info, Node: Property Syntax, Next: Special Properties, Up: Properties and Columns - -7.1 Property Syntax -=================== - -Properties are key–value pairs. When they are associated with a single -entry or with a tree they need to be inserted into a special drawer (see -*note Drawers::) with the name ‘PROPERTIES’, which has to be located -right below a headline, and its planning line (see *note Deadlines and -Scheduling::) when applicable. Each property is specified on a single -line, with the key—surrounded by colons—first, and the value after it. -Keys are case-insensitive. Here is an example: - - * CD collection - ** Classic - *** Goldberg Variations - :PROPERTIES: - :Title: Goldberg Variations - :Composer: J.S. Bach - :Artist: Glenn Gould - :Publisher: Deutsche Grammophon - :NDisks: 1 - :END: - - Depending on the value of ‘org-use-property-inheritance’, a property -set this way is associated either with a single entry, or with the -sub-tree defined by the entry, see *note Property Inheritance::. - - You may define the allowed values for a particular property ‘Xyz’ by -setting a property ‘Xyz_ALL’. This special property is _inherited_, so -if you set it in a level 1 entry, it applies to the entire tree. When -allowed values are defined, setting the corresponding property becomes -easier and is less prone to typing errors. For the example with the CD -collection, we can pre-define publishers and the number of disks in a -box like this: - - * CD collection - :PROPERTIES: - :NDisks_ALL: 1 2 3 4 - :Publisher_ALL: "Deutsche Grammophon" Philips EMI - :END: - - Properties can be inserted on buffer level. That means they apply -before the first headline and can be inherited by all entries in a file. -Property blocks defined before first headline needs to be located at the -top of the buffer, allowing only comments above. - - Properties can also be defined using lines like: - - #+PROPERTY: NDisks_ALL 1 2 3 4 - - If you want to add to the value of an existing property, append a ‘+’ -to the property name. The following results in the property ‘var’ -having the value ‘foo=1 bar=2’. - - #+PROPERTY: var foo=1 - #+PROPERTY: var+ bar=2 - - It is also possible to add to the values of inherited properties. -The following results in the ‘Genres’ property having the value ‘Classic -Baroque’ under the ‘Goldberg Variations’ subtree. - - * CD collection - ** Classic - :PROPERTIES: - :Genres: Classic - :END: - *** Goldberg Variations - :PROPERTIES: - :Title: Goldberg Variations - :Composer: J.S. Bach - :Artist: Glenn Gould - :Publisher: Deutsche Grammophon - :NDisks: 1 - :Genres+: Baroque - :END: - - Note that a property can only have one entry per drawer. - - Property values set with the global variable ‘org-global-properties’ -can be inherited by all entries in all Org files. - - The following commands help to work with properties: - -‘M-<TAB>’ (‘pcomplete’) - After an initial colon in a line, complete property keys. All keys - used in the current file are offered as possible completions. - -‘C-c C-x p’ (‘org-set-property’) - Set a property. This prompts for a property name and a value. If - necessary, the property drawer is created as well. - -‘C-u M-x org-insert-drawer’ - Insert a property drawer into the current entry. The drawer is - inserted early in the entry, but after the lines with planning - information like deadlines. If before first headline the drawer is - inserted at the top of the drawer after any potential comments. - -‘C-c C-c’ (‘org-property-action’) - With point in a property drawer, this executes property commands. - -‘C-c C-c s’ (‘org-set-property’) - Set a property in the current entry. Both the property and the - value can be inserted using completion. - -‘S-<RIGHT>’ (‘org-property-next-allowed-values’) -‘S-<LEFT>’ (‘org-property-previous-allowed-value’) - Switch property at point to the next/previous allowed value. - -‘C-c C-c d’ (‘org-delete-property’) - Remove a property from the current entry. - -‘C-c C-c D’ (‘org-delete-property-globally’) - Globally remove a property, from all entries in the current file. - -‘C-c C-c c’ (‘org-compute-property-at-point’) - Compute the property at point, using the operator and scope from - the nearest column format definition. - - -File: org.info, Node: Special Properties, Next: Property Searches, Prev: Property Syntax, Up: Properties and Columns - -7.2 Special Properties -====================== - -Special properties provide an alternative access method to Org mode -features, like the TODO state or the priority of an entry, discussed in -the previous chapters. This interface exists so that you can include -these states in a column view (see *note Column View::), or to use them -in queries. The following property names are special and should not be -used as keys in the properties drawer: - -‘ALLTAGS’ All tags, including inherited ones. -‘BLOCKED’ ‘t’ if task is currently blocked by children or siblings. -‘CATEGORY’ The category of an entry. -‘CLOCKSUM’ The sum of CLOCK intervals in the subtree. ‘org-clock-sum’ - must be run first to compute the values in the current buffer. -‘CLOCKSUM_T’ The sum of CLOCK intervals in the subtree for today. - ‘org-clock-sum-today’ must be run first to compute the - values in the current buffer. -‘CLOSED’ When was this entry closed? -‘DEADLINE’ The deadline timestamp. -‘FILE’ The filename the entry is located in. -‘ITEM’ The headline of the entry. -‘PRIORITY’ The priority of the entry, a string with a single letter. -‘SCHEDULED’ The scheduling timestamp. -‘TAGS’ The tags defined directly in the headline. -‘TIMESTAMP’ The first keyword-less timestamp in the entry. -‘TIMESTAMP_IA’ The first inactive timestamp in the entry. -‘TODO’ The TODO keyword of the entry. - - -File: org.info, Node: Property Searches, Next: Property Inheritance, Prev: Special Properties, Up: Properties and Columns - -7.3 Property Searches -===================== - -To create sparse trees and special lists with selection based on -properties, the same commands are used as for tag searches (see *note -Tag Searches::). - -‘C-c / m’ or ‘C-c \’ (‘org-match-sparse-tree’) - Create a sparse tree with all matching entries. With a ‘C-u’ - prefix argument, ignore headlines that are not a TODO line. - -‘M-x org-agenda m’ (‘org-tags-view’) - Create a global list of tag/property matches from all agenda files. - -‘M-x org-agenda M’ (‘org-tags-view’) - Create a global list of tag matches from all agenda files, but - check only TODO items and force checking of subitems (see the - option ‘org-tags-match-list-sublevels’). - - The syntax for the search string is described in *note Matching tags -and properties::. - - There is also a special command for creating sparse trees based on a -single property: - -‘C-c / p’ - Create a sparse tree based on the value of a property. This first - prompts for the name of a property, and then for a value. A sparse - tree is created with all entries that define this property with the - given value. If you enclose the value in curly braces, it is - interpreted as a regular expression and matched against the - property values (see *note Regular Expressions::). - - -File: org.info, Node: Property Inheritance, Next: Column View, Prev: Property Searches, Up: Properties and Columns - -7.4 Property Inheritance -======================== - -The outline structure of Org documents lends itself to an inheritance -model of properties: if the parent in a tree has a certain property, the -children can inherit this property. Org mode does not turn this on by -default, because it can slow down property searches significantly and is -often not needed. However, if you find inheritance useful, you can turn -it on by setting the variable ‘org-use-property-inheritance’. It may be -set to ‘t’ to make all properties inherited from the parent, to a list -of properties that should be inherited, or to a regular expression that -matches inherited properties. If a property has the value ‘nil’, this -is interpreted as an explicit un-define of the property, so that -inheritance search stops at this value and returns ‘nil’. - - Org mode has a few properties for which inheritance is hard-coded, at -least for the special applications for which they are used: - -‘COLUMNS’ - The ‘COLUMNS’ property defines the format of column view (see *note - Column View::). It is inherited in the sense that the level where - a ‘COLUMNS’ property is defined is used as the starting point for a - column view table, independently of the location in the subtree - from where columns view is turned on. - -‘CATEGORY’ - For agenda view, a category set through a ‘CATEGORY’ property - applies to the entire subtree. - -‘ARCHIVE’ - For archiving, the ‘ARCHIVE’ property may define the archive - location for the entire subtree (see *note Moving subtrees::). - -‘LOGGING’ - The ‘LOGGING’ property may define logging settings for an entry or - a subtree (see *note Tracking TODO state changes::). - - -File: org.info, Node: Column View, Prev: Property Inheritance, Up: Properties and Columns - -7.5 Column View -=============== - -A great way to view and edit properties in an outline tree is _column -view_. In column view, each outline node is turned into a table row. -Columns in this table provide access to properties of the entries. Org -mode implements columns by overlaying a tabular structure over the -headline of each item. While the headlines have been turned into a -table row, you can still change the visibility of the outline tree. For -example, you get a compact table by switching to “contents” -view—‘S-<TAB>’ ‘S-<TAB>’, or simply ‘c’ while column view is active—but -you can still open, read, and edit the entry below each headline. Or, -you can switch to column view after executing a sparse tree command and -in this way get a table only for the selected items. Column view also -works in agenda buffers (see *note Agenda Views::) where queries have -collected selected items, possibly from a number of files. - -* Menu: - -* Defining columns:: The COLUMNS format property. -* Using column view:: How to create and use column view. -* Capturing column view:: A dynamic block for column view. - - -File: org.info, Node: Defining columns, Next: Using column view, Up: Column View - -7.5.1 Defining columns ----------------------- - -Setting up a column view first requires defining the columns. This is -done by defining a column format line. - -* Menu: - -* Scope of column definitions:: Where defined, where valid? -* Column attributes:: Appearance and content of a column. - - -File: org.info, Node: Scope of column definitions, Next: Column attributes, Up: Defining columns - -7.5.1.1 Scope of column definitions -................................... - -To specify a format that only applies to a specific tree, add a -‘COLUMNS’ property to the top node of that tree, for example: - - ** Top node for columns view - :PROPERTIES: - :COLUMNS: %25ITEM %TAGS %PRIORITY %TODO - :END: - - A ‘COLUMNS’ property within a property drawer before first headline -will apply to the entire file. As an addition to property drawers, -keywords can also be defined for an entire file using a line like: - - #+COLUMNS: %25ITEM %TAGS %PRIORITY %TODO - - If a ‘COLUMNS’ property is present in an entry, it defines columns -for the entry itself, and for the entire subtree below it. Since the -column definition is part of the hierarchical structure of the document, -you can define columns on level 1 that are general enough for all -sublevels, and more specific columns further down, when you edit a -deeper part of the tree. - - -File: org.info, Node: Column attributes, Prev: Scope of column definitions, Up: Defining columns - -7.5.1.2 Column attributes -......................... - -A column definition sets the attributes of a column. The general -definition looks like this: - - %[WIDTH]PROPERTY[(TITLE)][{SUMMARY-TYPE}] - -Except for the percent sign and the property name, all items are -optional. The individual parts have the following meaning: - -WIDTH - An integer specifying the width of the column in characters. If - omitted, the width is determined automatically. - -PROPERTY - The property that should be edited in this column. Special - properties representing meta data are allowed here as well (see - *note Special Properties::). - -TITLE - The header text for the column. If omitted, the property name is - used. - -SUMMARY-TYPE - The summary type. If specified, the column values for parent nodes - are computed from the children(1). - - Supported summary types are: - - ‘+’ Sum numbers in this column. - ‘+;%.1f’ Like ‘+’, but format result with ‘%.1f’. - ‘$’ Currency, short for ‘+;%.2f’. - ‘min’ Smallest number in column. - ‘max’ Largest number. - ‘mean’ Arithmetic mean of numbers. - ‘X’ Checkbox status, ‘[X]’ if all children are ‘[X]’. - ‘X/’ Checkbox status, ‘[n/m]’. - ‘X%’ Checkbox status, ‘[n%]’. - ‘:’ Sum times, HH:MM, plain numbers are minutes. - ‘:min’ Smallest time value in column. - ‘:max’ Largest time value. - ‘:mean’ Arithmetic mean of time values. - ‘@min’ Minimum age(2) (in days/hours/mins/seconds). - ‘@max’ Maximum age (in days/hours/mins/seconds). - ‘@mean’ Arithmetic mean of ages (in days/hours/mins/seconds). - ‘est+’ Add low-high estimates. - - You can also define custom summary types by setting - ‘org-columns-summary-types’. - - The ‘est+’ summary type requires further explanation. It is used for -combining estimates, expressed as low-high ranges. For example, instead -of estimating a particular task will take 5 days, you might estimate it -as 5–6 days if you’re fairly confident you know how much work is -required, or 1–10 days if you do not really know what needs to be done. -Both ranges average at 5.5 days, but the first represents a more -predictable delivery. - - When combining a set of such estimates, simply adding the lows and -highs produces an unrealistically wide result. Instead, ‘est+’ adds the -statistical mean and variance of the subtasks, generating a final -estimate from the sum. For example, suppose you had ten tasks, each of -which was estimated at 0.5 to 2 days of work. Straight addition -produces an estimate of 5 to 20 days, representing what to expect if -everything goes either extremely well or extremely poorly. In contrast, -‘est+’ estimates the full job more realistically, at 10–15 days. - - Here is an example for a complete columns definition, along with -allowed values(3). - - :COLUMNS: %25ITEM %9Approved(Approved?){X} %Owner %11Status \ - %10Time_Estimate{:} %CLOCKSUM %CLOCKSUM_T - :Owner_ALL: Tammy Mark Karl Lisa Don - :Status_ALL: "In progress" "Not started yet" "Finished" "" - :Approved_ALL: "[ ]" "[X]" - -The first column, ‘%25ITEM’, means the first 25 characters of the item -itself, i.e., of the headline. You probably always should start the -column definition with the ‘ITEM’ specifier. The other specifiers -create columns ‘Owner’ with a list of names as allowed values, for -‘Status’ with four different possible values, and for a checkbox field -‘Approved’. When no width is given after the ‘%’ character, the column -is exactly as wide as it needs to be in order to fully display all -values. The ‘Approved’ column does have a modified title (‘Approved?’, -with a question mark). Summaries are created for the ‘Time_Estimate’ -column by adding time duration expressions like HH:MM, and for the -‘Approved’ column, by providing an ‘[X]’ status if all children have -been checked. The ‘CLOCKSUM’ and ‘CLOCKSUM_T’ columns are special, they -lists the sums of CLOCK intervals in the subtree, either for all clocks -or just for today. - - ---------- Footnotes ---------- - - (1) If more than one summary type applies to the same property, the -parent values are computed according to the first of them. - - (2) An age can be defined as a duration, using units defined in -‘org-duration-units’, e.g., ‘3d 1h’. If any value in the column is as -such, the summary is also expressed as a duration. - - (3) Please note that the ‘COLUMNS’ definition must be on a single -line; it is wrapped here only because of formatting constraints. - - -File: org.info, Node: Using column view, Next: Capturing column view, Prev: Defining columns, Up: Column View - -7.5.2 Using column view ------------------------ - -Turning column view on or off -............................. - -‘C-c C-x C-c’ (‘org-columns’) - Turn on column view. If point is before the first headline in the - file, column view is turned on for the entire file, using the - ‘#+COLUMNS’ definition. If point is somewhere inside the outline, - this command searches the hierarchy, up from point, for a ‘COLUMNS’ - property that defines a format. When one is found, the column view - table is established for the tree starting at the entry that - contains the ‘COLUMNS’ property. If no such property is found, the - format is taken from the ‘#+COLUMNS’ line or from the variable - ‘org-columns-default-format’, and column view is established for - the current entry and its subtree. - -‘r’ or ‘g’ on a columns view line (‘org-columns-redo’) - Recreate the column view, to include recent changes made in the - buffer. - -‘C-c C-c’ or ‘q’ on a columns view line (‘org-columns-quit’) - Exit column view. - -Editing values -.............. - -‘<LEFT>’, ‘<RIGHT>’, ‘<UP>’, ‘<DOWN>’ - Move through the column view from field to field. - -‘1..9,0’ - Directly select the Nth allowed value, ‘0’ selects the 10th value. - -‘n’ or ‘S-<RIGHT>’ (‘org-columns-next-allowed-value’) -‘p’ or ‘S-<LEFT>’ (‘org-columns-previous-allowed-value’) - Switch to the next/previous allowed value of the field. For this, - you have to have specified allowed values for a property. - -‘e’ (‘org-columns-edit-value’) - Edit the property at point. For the special properties, this - invokes the same interface that you normally use to change that - property. For example, the tag completion or fast selection - interface pops up when editing a ‘TAGS’ property. - -‘C-c C-c’ (‘org-columns-toggle-or-columns-quit’) - When there is a checkbox at point, toggle it. Else exit column - view. - -‘v’ (‘org-columns-show-value’) - View the full value of this property. This is useful if the width - of the column is smaller than that of the value. - -‘a’ (‘org-columns-edit-allowed’) - Edit the list of allowed values for this property. If the list is - found in the hierarchy, the modified values is stored there. If no - list is found, the new value is stored in the first entry that is - part of the current column view. - -Modifying column view on-the-fly -................................ - -‘<’ (‘org-columns-narrow’) -‘>’ (‘org-columns-widen’) - Make the column narrower/wider by one character. - -‘S-M-<RIGHT>’ (‘org-columns-new’) - Insert a new column, to the left of the current column. - -‘S-M-<LEFT>’ (‘org-columns-delete’) - Delete the current column. - - -File: org.info, Node: Capturing column view, Prev: Using column view, Up: Column View - -7.5.3 Capturing column view ---------------------------- - -Since column view is just an overlay over a buffer, it cannot be -exported or printed directly. If you want to capture a column view, use -a ‘columnview’ dynamic block (see *note Dynamic Blocks::). The frame of -this block looks like this: - - * The column view - #+BEGIN: columnview :hlines 1 :id "label" - - #+END: - - This dynamic block has the following parameters: - -‘:id’ - This is the most important parameter. Column view is a feature - that is often localized to a certain (sub)tree, and the capture - block might be at a different location in the file. To identify - the tree whose view to capture, you can use four values: - - ‘local’ - Use the tree in which the capture block is located. - - ‘global’ - Make a global view, including all headings in the file. - - ‘file:FILENAME’ - Run column view at the top of the FILENAME file. - - ‘LABEL’ - Call column view in the tree that has an ‘ID’ property with - the value LABEL. You can use ‘M-x org-id-copy’ to create a - globally unique ID for the current entry and copy it to the - kill-ring. - -‘:match’ - When set to a string, use this as a tags/property match filter to - select only a subset of the headlines in the scope set by the ‘:id’ - parameter. - -‘:hlines’ - When ‘t’, insert an hline after every line. When a number N, - insert an hline before each headline with level ‘<= N’. - -‘:vlines’ - When non-‘nil’, force column groups to get vertical lines. - -‘:maxlevel’ - When set to a number, do not capture entries below this level. - -‘:skip-empty-rows’ - When non-‘nil’, skip rows where the only non-empty specifier of the - column view is ‘ITEM’. - -‘:exclude-tags’ - List of tags to exclude from column view table: entries with these - tags will be excluded from the column view. - -‘:indent’ - When non-‘nil’, indent each ‘ITEM’ field according to its level. - -‘:format’ - Specify a column attribute (see *note Column attributes::) for the - dynamic block. - - The following commands insert or update the dynamic block: - -‘org-columns-insert-dblock’ - Insert a dynamic block capturing a column view. Prompt for the - scope or ID of the view. - - This command can be invoked by calling - ‘org-dynamic-block-insert-dblock’ (‘C-c C-x x’) and selecting - “columnview” (see *note Dynamic Blocks::). - -‘C-c C-c’ ‘C-c C-x C-u’ (‘org-dblock-update’) - Update dynamic block at point. point needs to be in the ‘#+BEGIN’ - line of the dynamic block. - -‘C-u C-c C-x C-u’ (‘org-update-all-dblocks’) - Update all dynamic blocks (see *note Dynamic Blocks::). This is - useful if you have several clock table blocks, column-capturing - blocks or other dynamic blocks in a buffer. - - You can add formulas to the column view table and you may add -plotting instructions in front of the table—these survive an update of -the block. If there is a ‘TBLFM’ keyword after the table, the table is -recalculated automatically after an update. - - An alternative way to capture and process property values into a -table is provided by Eric Schulte’s ‘org-collector.el’, which is a -package in ‘org-contrib’(1). It provides a general API to collect -properties from entries in a certain scope, and arbitrary Lisp -expressions to process these values before inserting them into a table -or a dynamic block. - - ---------- Footnotes ---------- - - (1) Contributed packages are not part of Emacs, but are distributed -with the main distribution of Org—visit <https://orgmode.org>. - - -File: org.info, Node: Dates and Times, Next: Refiling and Archiving, Prev: Properties and Columns, Up: Top - -8 Dates and Times -***************** - -To assist project planning, TODO items can be labeled with a date and/or -a time. The specially formatted string carrying the date and time -information is called a _timestamp_ in Org mode. This may be a little -confusing because timestamp is often used as indicating when something -was created or last changed. However, in Org mode this term is used in -a much wider sense. - -* Menu: - -* Timestamps:: Assigning a time to a tree entry. -* Creating Timestamps:: Commands to insert timestamps. -* Deadlines and Scheduling:: Planning your work. -* Clocking Work Time:: Tracking how long you spend on a task. -* Effort Estimates:: Planning work effort in advance. -* Timers:: Notes with a running timer. - - -File: org.info, Node: Timestamps, Next: Creating Timestamps, Up: Dates and Times - -8.1 Timestamps -============== - -A timestamp is a specification of a date (possibly with a time or a -range of times) in a special format, either ‘<2003-09-16 Tue>’ or -‘<2003-09-16 Tue 09:39>’ or ‘<2003-09-16 Tue 12:00-12:30>’(1). A -timestamp can appear anywhere in the headline or body of an Org tree -entry. Its presence causes entries to be shown on specific dates in the -agenda (see *note Weekly/daily agenda::). We distinguish: - -Plain timestamp; Event; Appointment - A simple timestamp just assigns a date/time to an item. This is - just like writing down an appointment or event in a paper agenda. - In the agenda display, the headline of an entry associated with a - plain timestamp is shown exactly on that date. - - * Meet Peter at the movies - <2006-11-01 Wed 19:15> - * Discussion on climate change - <2006-11-02 Thu 20:00-22:00> - -Timestamp with repeater interval - A timestamp may contain a _repeater interval_, indicating that it - applies not only on the given date, but again and again after a - certain interval of N days (d), weeks (w), months (m), or years - (y). The following shows up in the agenda every Wednesday: - - * Pick up Sam at school - <2007-05-16 Wed 12:30 +1w> - -Diary-style expression entries - For more complex date specifications, Org mode supports using the - special expression diary entries implemented in the Emacs Calendar - package(2). For example, with optional time: - - * 22:00-23:00 The nerd meeting on every 2nd Thursday of the month - <%%(diary-float t 4 2)> - -Time/Date range - Two timestamps connected by ‘--’ denote a range. The headline is - shown on the first and last day of the range, and on any dates that - are displayed and fall in the range. Here is an example: - - ** Meeting in Amsterdam - <2004-08-23 Mon>--<2004-08-26 Thu> - -Inactive timestamp - Just like a plain timestamp, but with square brackets instead of - angular ones. These timestamps are inactive in the sense that they - do _not_ trigger an entry to show up in the agenda. - - * Gillian comes late for the fifth time - [2006-11-01 Wed] - - ---------- Footnotes ---------- - - (1) The Org date format is inspired by the standard ISO 8601 -date/time format. To use an alternative format, see *note Custom time -format::. The day name is optional when you type the date yourself. -However, any date inserted or modified by Org adds that day name, for -reading convenience. - - (2) When working with the standard diary expression functions, you -need to be very careful with the order of the arguments. That order -depends evilly on the variable ‘calendar-date-style’. For example, to -specify a date December 12, 2005, the call might look like ‘(diary-date -12 1 2005)’ or ‘(diary-date 1 12 2005)’ or ‘(diary-date 2005 12 1)’, -depending on the settings. This has been the source of much confusion. -Org mode users can resort to special versions of these functions like -‘org-date’ or ‘org-anniversary’. These work just like the corresponding -‘diary-’ functions, but with stable ISO order of arguments (year, month, -day) wherever applicable, independent of the value of -‘calendar-date-style’. - - -File: org.info, Node: Creating Timestamps, Next: Deadlines and Scheduling, Prev: Timestamps, Up: Dates and Times - -8.2 Creating Timestamps -======================= - -For Org mode to recognize timestamps, they need to be in the specific -format. All commands listed below produce timestamps in the correct -format. - -‘C-c .’ (‘org-time-stamp’) - Prompt for a date and insert a corresponding timestamp. When point - is at an existing timestamp in the buffer, the command is used to - modify this timestamp instead of inserting a new one. When this - command is used twice in succession, a time range is inserted. - - When called with a prefix argument, use the alternative format - which contains date and time. The default time can be rounded to - multiples of 5 minutes. See the option - ‘org-time-stamp-rounding-minutes’. - - With two prefix arguments, insert an active timestamp with the - current time without prompting. - -‘C-c !’ (‘org-time-stamp-inactive’) - Like ‘C-c .’, but insert an inactive timestamp that does not cause - an agenda entry. - -‘C-c C-c’ - Normalize timestamp, insert or fix day name if missing or wrong. - -‘C-c <’ (‘org-date-from-calendar’) - Insert a timestamp corresponding to point date in the calendar. - -‘C-c >’ (‘org-goto-calendar’) - Access the Emacs calendar for the current date. If there is a - timestamp in the current line, go to the corresponding date - instead. - -‘C-c C-o’ (‘org-open-at-point’) - Access the agenda for the date given by the timestamp or -range at - point (see *note Weekly/daily agenda::). - -‘S-<LEFT>’ (‘org-timestamp-down-day’) -‘S-<RIGHT>’ (‘org-timestamp-up-day’) - Change date at point by one day. These key bindings conflict with - shift-selection and related modes (see *note Conflicts::). - -‘S-<UP>’ (‘org-timestamp-up’) -‘S-<DOWN>’ (‘org-timestamp-down’) - On the beginning or enclosing bracket of a timestamp, change its - type. Within a timestamp, change the item under point. Point can - be on a year, month, day, hour or minute. When the timestamp - contains a time range like ‘15:30-16:30’, modifying the first time - also shifts the second, shifting the time block with constant - length. To change the length, modify the second time. Note that - if point is in a headline and not at a timestamp, these same keys - modify the priority of an item (see *note Priorities::). The key - bindings also conflict with shift-selection and related modes (see - *note Conflicts::). - -‘C-c C-y’ (‘org-evaluate-time-range’) - Evaluate a time range by computing the difference between start and - end. With a prefix argument, insert result after the time range - (in a table: into the following column). - -* Menu: - -* The date/time prompt:: How Org mode helps you enter dates and times. -* Custom time format:: Making dates look different. - - -File: org.info, Node: The date/time prompt, Next: Custom time format, Up: Creating Timestamps - -8.2.1 The date/time prompt --------------------------- - -When Org mode prompts for a date/time, the default is shown in default -date/time format, and the prompt therefore seems to ask for a specific -format. But it in fact accepts date/time information in a variety of -formats. Generally, the information should start at the beginning of -the string. Org mode finds whatever information is in there and derives -anything you have not specified from the _default date and time_. The -default is usually the current date and time, but when modifying an -existing timestamp, or when entering the second stamp of a range, it is -taken from the stamp in the buffer. When filling in information, Org -mode assumes that most of the time you want to enter a date in the -future: if you omit the month/year and the given day/month is _before_ -today, it assumes that you mean a future date(1). If the date has been -automatically shifted into the future, the time prompt shows this with -‘(=>F)’. - - For example, let’s assume that today is *June 13, 2006*. Here is how -various inputs are interpreted, the items filled in by Org mode are in -*bold*. - -‘3-2-5’ ⇒ 2003-02-05 -‘2/5/3’ ⇒ 2003-02-05 -‘14’ ⇒ *2006*-*06*-14 -‘12’ ⇒ *2006*-*07*-12 -‘2/5’ ⇒ *2007*-02-05 -‘Fri’ ⇒ nearest Friday (default date or later) -‘sep 15’ ⇒ *2006*-09-15 -‘feb 15’ ⇒ *2007*-02-15 -‘sep 12 9’ ⇒ 2009-09-12 -‘12:45’ ⇒ *2006*-*06*-*13* 12:45 -‘22 sept 0:34’ ⇒ *2006*-09-22 0:34 -‘w4’ ⇒ ISO week for of the current year *2006* -‘2012 w4 fri’ ⇒ Friday of ISO week 4 in 2012 -‘2012-w04-5’ ⇒ Same as above - - Furthermore you can specify a relative date by giving, as the _first_ -thing in the input: a plus/minus sign, a number and a letter—‘h’, ‘d’, -‘w’, ‘m’ or ‘y’—to indicate a change in hours, days, weeks, months, or -years. With ‘h’ the date is relative to the current time, with the -other letters and a single plus or minus, the date is relative to today -at 00:00. With a double plus or minus, it is relative to the default -date. If instead of a single letter, you use the abbreviation of day -name, the date is the Nth such day, e.g.: - -‘+0’ ⇒ today -‘.’ ⇒ today -‘+2h’ ⇒ two hours from now -‘+4d’ ⇒ four days from today -‘+4’ ⇒ same as +4d -‘+2w’ ⇒ two weeks from today -‘++5’ ⇒ five days from default date -‘+2tue’ ⇒ second Tuesday from now - - The function understands English month and weekday abbreviations. If -you want to use un-abbreviated names and/or other languages, configure -the variables ‘parse-time-months’ and ‘parse-time-weekdays’. - - Not all dates can be represented in a given Emacs implementation. By -default Org mode forces dates into the compatibility range 1970–2037 -which works on all Emacs implementations. If you want to use dates -outside of this range, read the docstring of the variable -‘org-read-date-force-compatible-dates’. - - You can specify a time range by giving start and end times or by -giving a start time and a duration (in HH:MM format). Use one or two -dash(es) as the separator in the former case and use ‘+’ as the -separator in the latter case, e.g.: - -‘11am-1:15pm’ ⇒ 11:00-13:15 -‘11h-13h15’ ⇒ same as above -‘11am--1:15pm’ ⇒ same as above -‘11am+2:15’ ⇒ same as above - - Parallel to the minibuffer prompt, a calendar is popped up(2). When -you exit the date prompt, either by clicking on a date in the calendar, -or by pressing ‘<RET>’, the date selected in the calendar is combined -with the information entered at the prompt. You can control the -calendar fully from the minibuffer: - -‘<RET>’ Choose date at point in calendar. -‘mouse-1’ Select date by clicking on it. -‘S-<RIGHT>’ One day forward. -‘S-<LEFT>’ One day backward. -‘S-<DOWN>’ One week forward. -‘S-<UP>’ One week backward. -‘M-S-<RIGHT>’ One month forward. -‘M-S-<LEFT>’ One month backward. -‘>’ Scroll calendar forward by one month. -‘<’ Scroll calendar backward by one month. -‘M-v’ Scroll calendar forward by 3 months. -‘C-v’ Scroll calendar backward by 3 months. -‘C-.’ Select today’s date(3) - - The actions of the date/time prompt may seem complex, but I assure -you they will grow on you, and you will start getting annoyed by pretty -much any other way of entering a date/time out there. To help you -understand what is going on, the current interpretation of your input is -displayed live in the minibuffer(4). - - ---------- Footnotes ---------- - - (1) See the variable ‘org-read-date-prefer-future’. You may set that -variable to the symbol ‘time’ to even make a time before now shift the -date to tomorrow. - - (2) If you do not need/want the calendar, configure the variable -‘org-popup-calendar-for-date-prompt’. - - (3) You can also use the calendar command ‘.’ to jump to today’s -date, but if you are inserting an hour specification for your timestamp, -‘.’ will then insert a dot after the hour. By contrast, ‘C-.’ will -always jump to today’s date. - - (4) If you find this distracting, turn off the display with -‘org-read-date-display-live’. - - -File: org.info, Node: Custom time format, Prev: The date/time prompt, Up: Creating Timestamps - -8.2.2 Custom time format ------------------------- - -Org mode uses the standard ISO notation for dates and times as it is -defined in ISO 8601. If you cannot get used to this and require another -representation of date and time to keep you happy, you can get it by -customizing the variables ‘org-display-custom-times’ and -‘org-time-stamp-custom-formats’. - -‘C-c C-x C-t’ (‘org-toggle-time-stamp-overlays’) - Toggle the display of custom formats for dates and times. - - Org mode needs the default format for scanning, so the custom -date/time format does not _replace_ the default format. Instead, it is -put _over_ the default format using text properties. This has the -following consequences: - - • You cannot place point onto a timestamp anymore, only before or - after. - - • The ‘S-<UP>’ and ‘S-<DOWN>’ keys can no longer be used to adjust - each component of a timestamp. If point is at the beginning of the - stamp, ‘S-<UP>’ and ‘S-<DOWN>’ change the stamp by one day, just - like ‘S-<LEFT>’ ‘S-<RIGHT>’. At the end of the stamp, change the - time by one minute. - - • If the timestamp contains a range of clock times or a repeater, - these are not overlaid, but remain in the buffer as they were. - - • When you delete a timestamp character-by-character, it only - disappears from the buffer after _all_ (invisible) characters - belonging to the ISO timestamp have been removed. - - • If the custom timestamp format is longer than the default and you - are using dates in tables, table alignment will be messed up. If - the custom format is shorter, things do work as expected. - - -File: org.info, Node: Deadlines and Scheduling, Next: Clocking Work Time, Prev: Creating Timestamps, Up: Dates and Times - -8.3 Deadlines and Scheduling -============================ - -A timestamp may be preceded by special keywords to facilitate planning. -Both the timestamp and the keyword have to be positioned immediately -after the task they refer to. - -‘DEADLINE’ - Meaning: the task—most likely a TODO item, though not - necessarily—is supposed to be finished on that date. - - On the deadline date, the task is listed in the agenda. In - addition, the agenda for _today_ carries a warning about the - approaching or missed deadline, starting - ‘org-deadline-warning-days’ before the due date, and continuing - until the entry is marked as done. An example: - - *** TODO write article about the Earth for the Guide - DEADLINE: <2004-02-29 Sun> - The editor in charge is [[bbdb:Ford Prefect]] - - You can specify a different lead time for warnings for a specific - deadlines using the following syntax. Here is an example with a - warning period of 5 days ‘DEADLINE: <2004-02-29 Sun -5d>’. This - warning is deactivated if the task gets scheduled and you set - ‘org-agenda-skip-deadline-prewarning-if-scheduled’ to ‘t’. - -‘SCHEDULED’ - Meaning: you are planning to start working on that task on the - given date. - - The headline is listed under the given date(1). In addition, a - reminder that the scheduled date has passed is present in the - compilation for _today_, until the entry is marked as done, i.e., - the task is automatically forwarded until completed. - - *** TODO Call Trillian for a date on New Years Eve. - SCHEDULED: <2004-12-25 Sat> - - If you want to _delay_ the display of this task in the agenda, use - ‘SCHEDULED: <2004-12-25 Sat -2d>’: the task is still scheduled on - the 25th but will appear two days later. In case the task contains - a repeater, the delay is considered to affect all occurrences; if - you want the delay to only affect the first scheduled occurrence of - the task, use ‘--2d’ instead. See ‘org-scheduled-delay-days’ and - ‘org-agenda-skip-scheduled-delay-if-deadline’ for details on how to - control this globally or per agenda. - - Important: Scheduling an item in Org mode should _not_ be - understood in the same way that we understand _scheduling a - meeting_. Setting a date for a meeting is just a simple - appointment, you should mark this entry with a simple plain - timestamp, to get this item shown on the date where it - applies. This is a frequent misunderstanding by Org users. - In Org mode, _scheduling_ means setting a date when you want - to start working on an action item. - - You may use timestamps with repeaters in scheduling and deadline -entries. Org mode issues early and late warnings based on the -assumption that the timestamp represents the _nearest instance_ of the -repeater. However, the use of diary expression entries like - - <%%(diary-float t 42)> - -in scheduling and deadline timestamps is limited. Org mode does not -know enough about the internals of each function to issue early and late -warnings. However, it shows the item on each day where the expression -entry matches. - -* Menu: - -* Inserting deadline/schedule:: Planning items. -* Repeated tasks:: Items that show up again and again. - - ---------- Footnotes ---------- - - (1) It will still be listed on that date after it has been marked as -done. If you do not like this, set the variable -‘org-agenda-skip-scheduled-if-done’. - - -File: org.info, Node: Inserting deadline/schedule, Next: Repeated tasks, Up: Deadlines and Scheduling - -8.3.1 Inserting deadlines or schedules --------------------------------------- - -The following commands allow you to quickly insert a deadline or to -schedule an item:(1) - -‘C-c C-d’ (‘org-deadline’) - Insert ‘DEADLINE’ keyword along with a stamp. The insertion - happens in the line directly following the headline. Remove any - ‘CLOSED’ timestamp . When called with a prefix argument, also - remove any existing deadline from the entry. Depending on the - variable ‘org-log-redeadline’, take a note when changing an - existing deadline(2). - -‘C-c C-s’ (‘org-schedule’) - Insert ‘SCHEDULED’ keyword along with a stamp. The insertion - happens in the line directly following the headline. Remove any - ‘CLOSED’ timestamp. When called with a prefix argument, also - remove the scheduling date from the entry. Depending on the - variable ‘org-log-reschedule’, take a note when changing an - existing scheduling time(3). - -‘C-c / d’ (‘org-check-deadlines’) - Create a sparse tree with all deadlines that are either past-due, - or which will become due within ‘org-deadline-warning-days’. With - ‘C-u’ prefix, show all deadlines in the file. With a numeric - prefix, check that many days. For example, ‘C-1 C-c / d’ shows all - deadlines due tomorrow. - -‘C-c / b’ (‘org-check-before-date’) - Sparse tree for deadlines and scheduled items before a given date. - -‘C-c / a’ (‘org-check-after-date’) - Sparse tree for deadlines and scheduled items after a given date. - - Note that ‘org-schedule’ and ‘org-deadline’ supports setting the date -by indicating a relative time e.g., ‘+1d’ sets the date to the next day -after today, and ‘--1w’ sets the date to the previous week before any -current timestamp. - - ---------- Footnotes ---------- - - (1) The ‘SCHEDULED’ and ‘DEADLINE’ dates are inserted on the line -right below the headline. Do not put any text between this line and the -headline. - - (2) Note the corresponding ‘STARTUP’ options ‘logredeadline’, -‘lognoteredeadline’, and ‘nologredeadline’. - - (3) Note the corresponding ‘STARTUP’ options ‘logreschedule’, -‘lognotereschedule’, and ‘nologreschedule’. - - -File: org.info, Node: Repeated tasks, Prev: Inserting deadline/schedule, Up: Deadlines and Scheduling - -8.3.2 Repeated tasks --------------------- - -Some tasks need to be repeated again and again. Org mode helps to -organize such tasks using a so-called repeater in a ‘DEADLINE’, -‘SCHEDULED’, or plain timestamps(1). In the following example: - - ** TODO Pay the rent - DEADLINE: <2005-10-01 Sat +1m> - -the ‘+1m’ is a repeater; the intended interpretation is that the task -has a deadline on ‘<2005-10-01>’ and repeats itself every (one) month -starting from that time. You can use yearly, monthly, weekly, daily and -hourly repeat cookies by using the ‘y’, ‘m’, ‘w’, ‘d’ and ‘h’ letters. -If you need both a repeater and a special warning period in a deadline -entry, the repeater should come first and the warning period last - - DEADLINE: <2005-10-01 Sat +1m -3d> - - Deadlines and scheduled items produce entries in the agenda when they -are over-due, so it is important to be able to mark such an entry as -done once you have done so. When you mark a ‘DEADLINE’ or a ‘SCHEDULED’ -with the TODO keyword ‘DONE’, it no longer produces entries in the -agenda. The problem with this is, however, is that then also the _next_ -instance of the repeated entry will not be active. Org mode deals with -this in the following way: when you try to mark such an entry as done, -using ‘C-c C-t’, it shifts the base date of the repeating timestamp by -the repeater interval, and immediately sets the entry state back to -TODO(2). In the example above, setting the state to ‘DONE’ would -actually switch the date like this: - - ** TODO Pay the rent - DEADLINE: <2005-11-01 Tue +1m> - - To mark a task with a repeater as DONE, use ‘C-- 1 C-c C-t’, i.e., -‘org-todo’ with a numeric prefix argument of ‘-1’. - - A timestamp(3) is added under the deadline, to keep a record that you -actually acted on the previous instance of this deadline. - - As a consequence of shifting the base date, this entry is no longer -visible in the agenda when checking past dates, but all future instances -will be visible. - - With the ‘+1m’ cookie, the date shift is always exactly one month. -So if you have not paid the rent for three months, marking this entry -DONE still keeps it as an overdue deadline. Depending on the task, this -may not be the best way to handle it. For example, if you forgot to -call your father for 3 weeks, it does not make sense to call him 3 times -in a single day to make up for it. Finally, there are tasks, like -changing batteries, which should always repeat a certain time _after_ -the last time you did it. For these tasks, Org mode has special -repeaters ‘++’ and ‘.+’. For example: - - ** TODO Call Father - DEADLINE: <2008-02-10 Sun ++1w> - Marking this DONE shifts the date by at least one week, but also - by as many weeks as it takes to get this date into the future. - However, it stays on a Sunday, even if you called and marked it - done on Saturday. - - ** TODO Empty kitchen trash - DEADLINE: <2008-02-08 Fri 20:00 ++1d> - Marking this DONE shifts the date by at least one day, and also - by as many days as it takes to get the timestamp into the future. - Since there is a time in the timestamp, the next deadline in the - future will be on today's date if you complete the task before - 20:00. - - ** TODO Check the batteries in the smoke detectors - DEADLINE: <2005-11-01 Tue .+1m> - Marking this DONE shifts the date to one month after today. - - ** TODO Wash my hands - DEADLINE: <2019-04-05 08:00 Sun .+1h> - Marking this DONE shifts the date to exactly one hour from now. - - You may have both scheduling and deadline information for a specific -task. If the repeater is set for the scheduling information only, you -probably want the repeater to be ignored after the deadline. If so, set -the variable ‘org-agenda-skip-scheduled-if-deadline-is-shown’ to -‘repeated-after-deadline’. However, any scheduling information without -a repeater is no longer relevant once the task is done, and thus, -removed upon repeating the task. If you want both scheduling and -deadline information to repeat after the same interval, set the same -repeater for both timestamps. - - An alternative to using a repeater is to create a number of copies of -a task subtree, with dates shifted in each copy. The command ‘C-c C-x -c’ was created for this purpose; it is described in *note Structure -Editing::. - - ---------- Footnotes ---------- - - (1) Org does not repeat inactive timestamps, however. See *note -Timestamps::. - - (2) In fact, the target state is taken from, in this sequence, the -‘REPEAT_TO_STATE’ property, the variable ‘org-todo-repeat-to-state’ if -it is a string, the previous TODO state if ‘org-todo-repeat-to-state’ is -‘t’, or the first state of the TODO state sequence. - - (3) You can change this using the option ‘org-log-repeat’, or the -‘STARTUP’ options ‘logrepeat’, ‘lognoterepeat’, and ‘nologrepeat’. With -‘lognoterepeat’, you will also be prompted for a note. - - -File: org.info, Node: Clocking Work Time, Next: Effort Estimates, Prev: Deadlines and Scheduling, Up: Dates and Times - -8.4 Clocking Work Time -====================== - -Org mode allows you to clock the time you spend on specific tasks in a -project. When you start working on an item, you can start the clock. -When you stop working on that task, or when you mark the task done, the -clock is stopped and the corresponding time interval is recorded. It -also computes the total time spent on each subtree(1) of a project. And -it remembers a history or tasks recently clocked, so that you can jump -quickly between a number of tasks absorbing your time. - - To save the clock history across Emacs sessions, use: - - (setq org-clock-persist 'history) - (org-clock-persistence-insinuate) - - When you clock into a new task after resuming Emacs, the incomplete -clock(2) is retrieved (see *note Resolving idle time (1)::) and you are -prompted about what to do with it. - -* Menu: - -* Clocking commands:: Starting and stopping a clock. -* The clock table:: Detailed reports. -* Resolving idle time:: Resolving time when you’ve been idle. - - ---------- Footnotes ---------- - - (1) Clocking only works if all headings are indented with less than -30 stars. This is a hard-coded limitation of ‘lmax’ in ‘org-clock-sum’. - - (2) To resume the clock under the assumption that you have worked on -this task while outside Emacs, use ‘(setq org-clock-persist t)’. - - -File: org.info, Node: Clocking commands, Next: The clock table, Up: Clocking Work Time - -8.4.1 Clocking commands ------------------------ - -‘C-c C-x C-i’ (‘org-clock-in’) - Start the clock on the current item (clock-in). This inserts the - ‘CLOCK’ keyword together with a timestamp. If this is not the - first clocking of this item, the multiple ‘CLOCK’ lines are wrapped - into a ‘LOGBOOK’ drawer (see also the variable - ‘org-clock-into-drawer’). You can also overrule the setting of - this variable for a subtree by setting a ‘CLOCK_INTO_DRAWER’ or - ‘LOG_INTO_DRAWER’ property. When called with a ‘C-u’ prefix - argument, select the task from a list of recently clocked tasks. - With two ‘C-u C-u’ prefixes, clock into the task at point and mark - it as the default task; the default task is always be available - with letter ‘d’ when selecting a clocking task. With three ‘C-u - C-u C-u’ prefixes, force continuous clocking by starting the clock - when the last clock stopped. - - While the clock is running, Org shows the current clocking time in - the mode line, along with the title of the task. The clock time - shown is all time ever clocked for this task and its children. If - the task has an effort estimate (see *note Effort Estimates::), the - mode line displays the current clocking time against it(1). If the - task is a repeating one (see *note Repeated tasks::), show only the - time since the last reset of the task(2). You can exercise more - control over show time with the ‘CLOCK_MODELINE_TOTAL’ property. - It may have the values ‘current’ to show only the current clocking - instance, ‘today’ to show all time clocked on this tasks today—see - also the variable ‘org-extend-today-until’, ‘all’ to include all - time, or ‘auto’ which is the default(3). Clicking with ‘mouse-1’ - onto the mode line entry pops up a menu with clocking options. - -‘C-c C-x C-o’ (‘org-clock-out’) - Stop the clock (clock-out). This inserts another timestamp at the - same location where the clock was last started. It also directly - computes the resulting time in inserts it after the time range as - ‘=>HH:MM’. See the variable ‘org-log-note-clock-out’ for the - possibility to record an additional note together with the - clock-out timestamp(4). - -‘C-c C-x C-x’ (‘org-clock-in-last’) - Re-clock the last clocked task. With one ‘C-u’ prefix argument, - select the task from the clock history. With two ‘C-u’ prefixes, - force continuous clocking by starting the clock when the last clock - stopped. - -‘C-c C-x C-e’ (‘org-clock-modify-effort-estimate’) - Update the effort estimate for the current clock task. - -‘C-c C-c’ or ‘C-c C-y’ (‘org-evaluate-time-range’) - Recompute the time interval after changing one of the timestamps. - This is only necessary if you edit the timestamps directly. If you - change them with ‘S-<cursor>’ keys, the update is automatic. - -‘C-S-<UP>’ (‘org-clock-timestamps-up’) -‘C-S-<DOWN>’ (‘org-clock-timestamps-down’) - On CLOCK log lines, increase/decrease both timestamps so that the - clock duration keeps the same value. - -‘S-M-<UP>’ (‘org-timestamp-up’) -‘S-M-<DOWN>’ (‘org-timestamp-down’) - On ‘CLOCK’ log lines, increase/decrease the timestamp at point and - the one of the previous, or the next, clock timestamp by the same - duration. For example, if you hit ‘S-M-<UP>’ to increase a - clocked-out timestamp by five minutes, then the clocked-in - timestamp of the next clock is increased by five minutes. - -‘C-c C-t’ (‘org-todo’) - Changing the TODO state of an item to DONE automatically stops the - clock if it is running in this same item. - -‘C-c C-x C-q’ (‘org-clock-cancel’) - Cancel the current clock. This is useful if a clock was started by - mistake, or if you ended up working on something else. - -‘C-c C-x C-j’ (‘org-clock-goto’) - Jump to the headline of the currently clocked in task. With a - ‘C-u’ prefix argument, select the target task from a list of - recently clocked tasks. - -‘C-c C-x C-d’ (‘org-clock-display’) - Display time summaries for each subtree in the current buffer. - This puts overlays at the end of each headline, showing the total - time recorded under that heading, including the time of any - subheadings. You can use visibility cycling to study the tree, but - the overlays disappear when you change the buffer (see variable - ‘org-remove-highlights-with-change’) or press ‘C-c C-c’. - - The ‘l’ key may be used in the agenda (see *note Weekly/daily -agenda::) to show which tasks have been worked on or closed during a -day. - - *Important:* note that both ‘org-clock-out’ and ‘org-clock-in-last’ -can have a global keybinding and do not modify the window disposition. - - ---------- Footnotes ---------- - - (1) To add an effort estimate “on the fly”, hook a function doing -this to ‘org-clock-in-prepare-hook’. - - (2) The last reset of the task is recorded by the ‘LAST_REPEAT’ -property. - - (3) See also the variable ‘org-clock-mode-line-total’. - - (4) The corresponding in-buffer setting is: ‘#+STARTUP: -lognoteclock-out’. - - -File: org.info, Node: The clock table, Next: Resolving idle time, Prev: Clocking commands, Up: Clocking Work Time - -8.4.2 The clock table ---------------------- - -Org mode can produce quite complex reports based on the time clocking -information. Such a report is called a _clock table_, because it is -formatted as one or several Org tables. - -‘org-clock-report’ - Insert or update a clock table. When called with a prefix - argument, jump to the first clock table in the current document and - update it. The clock table includes archived trees. - - This command can be invoked by calling - ‘org-dynamic-block-insert-dblock’ (‘C-c C-x x’) and selecting - “clocktable” (see *note Dynamic Blocks::). - -‘C-c C-c’ or ‘C-c C-x C-u’ (‘org-dblock-update’) - Update dynamic block at point. Point needs to be in the ‘BEGIN’ - line of the dynamic block. - -‘C-u C-c C-x C-u’ - Update all dynamic blocks (see *note Dynamic Blocks::). This is - useful if you have several clock table blocks in a buffer. - -‘S-<LEFT>’ -‘S-<RIGHT>’ (‘org-clocktable-try-shift’) - Shift the current ‘:block’ interval and update the table. Point - needs to be in the ‘#+BEGIN: clocktable’ line for this command. If - ‘:block’ is ‘today’, it is shifted to ‘today-1’, etc. - - Here is an example of the frame for a clock table as it is inserted -into the buffer by ‘org-clock-report’: - - #+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file - #+END: clocktable - - The ‘#+BEGIN’ line contains options to define the scope, structure, -and formatting of the report. Defaults for all these options can be -configured in the variable ‘org-clocktable-defaults’. - - First there are options that determine which clock entries are to be -selected: - -‘:maxlevel’ - Maximum level depth to which times are listed in the table. Clocks - at deeper levels are summed into the upper level. - -‘:scope’ - The scope to consider. This can be any of the following: - - ‘nil’ the current buffer or narrowed region - ‘file’ the full current buffer - ‘subtree’ the subtree where the clocktable is located - ‘treeN’ the surrounding level N tree, for example ‘tree3’ - ‘tree’ the surrounding level 1 tree - ‘agenda’ all agenda files - ‘("file" ...)’ scan these files - ‘FUNCTION’ scan files returned by calling FUNCTION with no argument - ‘file-with-archives’ current file and its archives - ‘agenda-with-archives’ all agenda files, including archives - -‘:block’ - The time block to consider. This block is specified either - absolutely, or relative to the current time and may be any of these - formats: - - ‘2007-12-31’ New year eve 2007 - ‘2007-12’ December 2007 - ‘2007-W50’ ISO-week 50 in 2007 - ‘2007-Q2’ 2nd quarter in 2007 - ‘2007’ the year 2007 - ‘today’, ‘yesterday’, ‘today-N’ a relative day - ‘thisweek’, ‘lastweek’, ‘thisweek-N’ a relative week - ‘thismonth’, ‘lastmonth’, ‘thismonth-N’ a relative month - ‘thisyear’, ‘lastyear’, ‘thisyear-N’ a relative year - ‘untilnow’(1) all clocked time ever - - When this option is not set, Org falls back to the value in - ‘org-clock-display-default-range’, which defaults to the current - year. - - Use ‘S-<LEFT>’ or ‘S-<RIGHT>’ to shift the time interval. - -‘:tstart’ - A time string specifying when to start considering times. Relative - times like ‘"<-2w>"’ can also be used. See *note Matching tags and - properties:: for relative time syntax. - -‘:tend’ - A time string specifying when to stop considering times. Relative - times like ‘"<now>"’ can also be used. See *note Matching tags and - properties:: for relative time syntax. - -‘:wstart’ - The starting day of the week. The default is 1 for Monday. - -‘:mstart’ - The starting day of the month. The default is 1 for the first. - -‘:step’ - Set to ‘day’, ‘week’, ‘semimonth’, ‘month’, or ‘year’ to split the - table into chunks. To use this, either ‘:block’, or ‘:tstart’ and - ‘:tend’ are required. - -‘:stepskip0’ - When non-‘nil’, do not show steps that have zero time. - -‘:fileskip0’ - When non-‘nil’, do not show table sections from files which did not - contribute. - -‘:match’ - A tags match to select entries that should contribute. See *note - Matching tags and properties:: for the match syntax. - - Then there are options that determine the formatting of the table. -There options are interpreted by the function -‘org-clocktable-write-default’, but you can specify your own function -using the ‘:formatter’ parameter. - -‘:emphasize’ - When non-‘nil’, emphasize level one and level two items. - -‘:lang’ - Language(2) to use for descriptive cells like “Task”. - -‘:link’ - Link the item headlines in the table to their origins. - -‘:narrow’ - An integer to limit the width of the headline column in the Org - table. If you write it like ‘50!’, then the headline is also - shortened in export. - -‘:indent’ - Indent each headline field according to its level. - -‘:hidefiles’ - Hide the file column when multiple files are used to produce the - table. - -‘:tcolumns’ - Number of columns to be used for times. If this is smaller than - ‘:maxlevel’, lower levels are lumped into one column. - -‘:level’ - Should a level number column be included? - -‘:sort’ - A cons cell containing the column to sort and a sorting type. - E.g., ‘:sort (1 . ?a)’ sorts the first column alphabetically. - -‘:compact’ - Abbreviation for ‘:level nil :indent t :narrow 40! :tcolumns 1’. - All are overwritten except if there is an explicit ‘:narrow’. - -‘:timestamp’ - A timestamp for the entry, when available. Look for ‘SCHEDULED’, - ‘DEADLINE’, ‘TIMESTAMP’ and ‘TIMESTAMP_IA’ special properties (see - *note Special Properties::), in this order. - -‘:tags’ - When this flag is non-‘nil’, show the headline’s tags. - -‘:properties’ - List of properties shown in the table. Each property gets its own - column. - -‘:inherit-props’ - When this flag is non-‘nil’, the values for ‘:properties’ are - inherited. - -‘:formula’ - Content of a ‘TBLFM’ keyword to be added and evaluated. As a - special case, ‘:formula %’ adds a column with % time. If you do - not specify a formula here, any existing formula below the clock - table survives updates and is evaluated. - -‘:formatter’ - A function to format clock data and insert it into the buffer. - - To get a clock summary of the current level 1 tree, for the current -day, you could write: - - #+BEGIN: clocktable :maxlevel 2 :block today :scope tree1 :link t - #+END: clocktable - -To use a specific time range you could write(3) - - #+BEGIN: clocktable :tstart "<2006-08-10 Thu 10:00>" - :tend "<2006-08-10 Thu 12:00>" - #+END: clocktable - -A range starting a week ago and ending right now could be written as - - #+BEGIN: clocktable :tstart "<-1w>" :tend "<now>" - #+END: clocktable - -A summary of the current subtree with % times would be - - #+BEGIN: clocktable :scope subtree :link t :formula % - #+END: clocktable - -A horizontally compact representation of everything clocked during last -week would be - - #+BEGIN: clocktable :scope agenda :block lastweek :compact t - #+END: clocktable - - ---------- Footnotes ---------- - - (1) When using ‘:step’, ‘untilnow’ starts from the beginning of 2003, -not the beginning of time. - - (2) Language terms can be set through the variable -‘org-clock-clocktable-language-setup’. - - (3) Note that all parameters must be specified in a single line—the -line is broken here only to fit it into the manual. - - -File: org.info, Node: Resolving idle time, Prev: The clock table, Up: Clocking Work Time - -8.4.3 Resolving idle time and continuous clocking -------------------------------------------------- - -Resolving idle time -................... - -If you clock in on a work item, and then walk away from your -computer—perhaps to take a phone call—you often need to “resolve” the -time you were away by either subtracting it from the current clock, or -applying it to another one. - - By customizing the variable ‘org-clock-idle-time’ to some integer, -such as 10 or 15, Emacs can alert you when you get back to your computer -after being idle for that many minutes(1), and ask what you want to do -with the idle time. There will be a question waiting for you when you -get back, indicating how much idle time has passed constantly updated -with the current amount, as well as a set of choices to correct the -discrepancy: - -‘k’ - To keep some or all of the minutes and stay clocked in, press ‘k’. - Org asks how many of the minutes to keep. Press ‘<RET>’ to keep - them all, effectively changing nothing, or enter a number to keep - that many minutes. - -‘K’ - If you use the shift key and press ‘K’, it keeps however many - minutes you request and then immediately clock out of that task. - If you keep all of the minutes, this is the same as just clocking - out of the current task. - -‘s’ - To keep none of the minutes, use ‘s’ to subtract all the away time - from the clock, and then check back in from the moment you - returned. - -‘S’ - To keep none of the minutes and just clock out at the start of the - away time, use the shift key and press ‘S’. Remember that using - shift always leave you clocked out, no matter which option you - choose. - -‘C’ - To cancel the clock altogether, use ‘C’. Note that if instead of - canceling you subtract the away time, and the resulting clock - amount is less than a minute, the clock is still canceled rather - than cluttering up the log with an empty entry. - - What if you subtracted those away minutes from the current clock, and -now want to apply them to a new clock? Simply clock in to any task -immediately after the subtraction. Org will notice that you have -subtracted time “on the books”, so to speak, and will ask if you want to -apply those minutes to the next task you clock in on. - - There is one other instance when this clock resolution magic occurs. -Say you were clocked in and hacking away, and suddenly your cat chased a -mouse who scared a hamster that crashed into your UPS’s power button! -You suddenly lose all your buffers, but thanks to auto-save you still -have your recent Org mode changes, including your last clock in. - - If you restart Emacs and clock into any task, Org will notice that -you have a dangling clock which was never clocked out from your last -session. Using that clock’s starting time as the beginning of the -unaccounted-for period, Org will ask how you want to resolve that time. -The logic and behavior is identical to dealing with away time due to -idleness; it is just happening due to a recovery event rather than a set -amount of idle time. - - You can also check all the files visited by your Org agenda for -dangling clocks at any time using ‘M-x org-resolve-clocks <RET>’ (or -‘C-c C-x C-z’). - -Continuous clocking -................... - -You may want to start clocking from the time when you clocked out the -previous task. To enable this systematically, set -‘org-clock-continuously’ to non-‘nil’. Each time you clock in, Org -retrieves the clock-out time of the last clocked entry for this session, -and start the new clock from there. - - If you only want this from time to time, use three universal prefix -arguments with ‘org-clock-in’ and two ‘C-u C-u’ with -‘org-clock-in-last’. - -Clocking out automatically after some idle time -............................................... - -When you often forget to clock out before being idle and you don’t want -to manually set the clocking time to take into account, you can set -‘org-clock-auto-clockout-timer’ to a number of seconds and add -‘(org-clock-auto-clockout-insinuate)’ to your ‘.emacs’ file. - - When the clock is running and Emacs is idle for more than this number -of seconds, the clock will be clocked out automatically. - - Use ‘M-x org-clock-toggle-auto-clockout RET’ to temporarily turn this -on or off. - - ---------- Footnotes ---------- - - (1) On computers using macOS, idleness is based on actual user -idleness, not just Emacs’ idle time. For X11, you can install a utility -program ‘x11idle.c’, available in the ‘org-contrib/’ repository, or -install the xprintidle package and set it to the variable -‘org-clock-x11idle-program-name’ if you are running Debian, to get the -same general treatment of idleness. On other systems, idle time refers -to Emacs idle time only. - - -File: org.info, Node: Effort Estimates, Next: Timers, Prev: Clocking Work Time, Up: Dates and Times - -8.5 Effort Estimates -==================== - -If you want to plan your work in a very detailed way, or if you need to -produce offers with quotations of the estimated work effort, you may -want to assign effort estimates to entries. If you are also clocking -your work, you may later want to compare the planned effort with the -actual working time, a great way to improve planning estimates. - - Effort estimates are stored in a special property ‘EFFORT’. Multiple -formats are supported, such as ‘3:12’, ‘1:23:45’, or ‘1d3h5min’; see the -file ‘org-duration.el’ for more detailed information about the format. - - You can set the effort for an entry with the following commands: - -‘C-c C-x e’ (‘org-set-effort’) - Set the effort estimate for the current entry. With a prefix - argument, set it to the next allowed value—see below. This command - is also accessible from the agenda with the ‘e’ key. - -‘C-c C-x C-e’ (‘org-clock-modify-effort-estimate’) - Modify the effort estimate of the item currently being clocked. - - Clearly the best way to work with effort estimates is through column -view (see *note Column View::). You should start by setting up discrete -values for effort estimates, and a ‘COLUMNS’ format that displays these -values together with clock sums—if you want to clock your time. For a -specific buffer you can use: - - #+PROPERTY: Effort_ALL 0 0:10 0:30 1:00 2:00 3:00 4:00 5:00 6:00 7:00 - #+COLUMNS: %40ITEM(Task) %17Effort(Estimated Effort){:} %CLOCKSUM - -or, even better, you can set up these values globally by customizing the -variables ‘org-global-properties’ and ‘org-columns-default-format’. In -particular if you want to use this setup also in the agenda, a global -setup may be advised. - - The way to assign estimates to individual items is then to switch to -column mode, and to use ‘S-<RIGHT>’ and ‘S-<LEFT>’ to change the value. -The values you enter are immediately summed up in the hierarchy. In the -column next to it, any clocked time is displayed. - - If you switch to column view in the daily/weekly agenda, the effort -column summarizes the estimated work effort for each day(1), and you can -use this to find space in your schedule. To get an overview of the -entire part of the day that is committed, you can set the option -‘org-agenda-columns-add-appointments-to-effort-sum’. The appointments -on a day that take place over a specified time interval are then also -added to the load estimate of the day. - - Effort estimates can be used in secondary agenda filtering that is -triggered with the ‘/’ key in the agenda (see *note Agenda Commands::). -If you have these estimates defined consistently, two or three key -presses narrow down the list to stuff that fits into an available time -slot. - - ---------- Footnotes ---------- - - (1) Please note the pitfalls of summing hierarchical data in a flat -list (see *note Agenda Column View::). - - -File: org.info, Node: Timers, Prev: Effort Estimates, Up: Dates and Times - -8.6 Taking Notes with a Relative Timer -====================================== - -Org provides two types of timers. There is a relative timer that counts -up, which can be useful when taking notes during, for example, a meeting -or a video viewing. There is also a countdown timer. - - The relative and countdown are started with separate commands. - -‘C-c C-x 0’ (‘org-timer-start’) - Start or reset the relative timer. By default, the timer is set to - 0. When called with a ‘C-u’ prefix, prompt the user for a starting - offset. If there is a timer string at point, this is taken as the - default, providing a convenient way to restart taking notes after a - break in the process. When called with a double prefix argument - ‘C-u C-u’, change all timer strings in the active region by a - certain amount. This can be used to fix timer strings if the timer - was not started at exactly the right moment. - -‘C-c C-x ;’ (‘org-timer-set-timer’) - Start a countdown timer. The user is prompted for a duration. - ‘org-timer-default-timer’ sets the default countdown value. Giving - a numeric prefix argument overrides this default value. This - command is available as ‘;’ in agenda buffers. - - Once started, relative and countdown timers are controlled with the -same commands. - -‘C-c C-x .’ (‘org-timer’) - Insert a relative time into the buffer. The first time you use - this, the timer starts. Using a prefix argument restarts it. - -‘C-c C-x -’ (‘org-timer-item’) - Insert a description list item with the current relative time. - With a prefix argument, first reset the timer to 0. - -‘M-<RET>’ (‘org-insert-heading’) - Once the timer list is started, you can also use ‘M-<RET>’ to - insert new timer items. - -‘C-c C-x ,’ (‘org-timer-pause-or-continue’) - Pause the timer, or continue it if it is already paused. - -‘C-c C-x _’ (‘org-timer-stop’) - Stop the timer. After this, you can only start a new timer, not - continue the old one. This command also removes the timer from the - mode line. - - -File: org.info, Node: Refiling and Archiving, Next: Capture and Attachments, Prev: Dates and Times, Up: Top - -9 Refiling and Archiving -************************ - -Once information is in the system, it may need to be moved around. Org -provides Refile, Copy and Archive commands for this. Refile and Copy -helps with moving and copying outlines. Archiving helps to keep the -system compact and fast. - -* Menu: - -* Refile and Copy:: Moving/copying a tree from one place to another. -* Archiving:: What to do with finished products. - - -File: org.info, Node: Refile and Copy, Next: Archiving, Up: Refiling and Archiving - -9.1 Refile and Copy -=================== - -When reviewing the captured data, you may want to refile or to copy some -of the entries into a different list, for example into a project. -Cutting, finding the right location, and then pasting the note is -cumbersome. To simplify this process, you can use the following special -command: - -‘C-c C-w’ (‘org-refile’) - Refile the entry or region at point. This command offers possible - locations for refiling the entry and lets you select one with - completion. The item (or all items in the region) is filed below - the target heading as a subitem. Depending on - ‘org-reverse-note-order’, it is either the first or last subitem. - - By default, all level 1 headlines in the current buffer are - considered to be targets, but you can have more complex definitions - across a number of files. See the variable ‘org-refile-targets’ - for details. If you would like to select a location via a - file-path-like completion along the outline path, see the variables - ‘org-refile-use-outline-path’ and - ‘org-outline-path-complete-in-steps’. If you would like to be able - to create new nodes as new parents for refiling on the fly, check - the variable ‘org-refile-allow-creating-parent-nodes’. When the - variable ‘org-log-refile’(1) is set, a timestamp or a note is - recorded whenever an entry is refiled. - -‘C-u C-c C-w’ - Use the refile interface to jump to a heading. - -‘C-u C-u C-c C-w’ (‘org-refile-goto-last-stored’) - Jump to the location where ‘org-refile’ last moved a tree to. - -‘C-2 C-c C-w’ - Refile as the child of the item currently being clocked. - -‘C-3 C-c C-w’ - Refile and keep the entry in place. Also see ‘org-refile-keep’ to - make this the default behavior, and beware that this may result in - duplicated ‘ID’ properties. - -‘C-0 C-c C-w’ or ‘C-u C-u C-u C-c C-w’ (‘org-refile-cache-clear’) - Clear the target cache. Caching of refile targets can be turned on - by setting ‘org-refile-use-cache’. To make the command see new - possible targets, you have to clear the cache with this command. - -‘C-c M-w’ (‘org-refile-copy’) - Copying works like refiling, except that the original note is not - deleted. - -‘C-c C-M-w’ (‘org-refile-reverse’) - Works like refiling, except that it temporarily toggles how the - value of ‘org-reverse-note-order’ applies to the current buffer. - So if ‘org-refile’ would append the entry as the last entry under - the target header, ‘org-refile-reverse’ will prepend it as the - first entry, and vice-versa. - - ---------- Footnotes ---------- - - (1) Note the corresponding ‘STARTUP’ options ‘logrefile’, -‘lognoterefile’, and ‘nologrefile’. - - -File: org.info, Node: Archiving, Prev: Refile and Copy, Up: Refiling and Archiving - -9.2 Archiving -============= - -When a project represented by a (sub)tree is finished, you may want to -move the tree out of the way and to stop it from contributing to the -agenda. Archiving is important to keep your working files compact and -global searches like the construction of agenda views fast. - -‘C-c C-x C-a’ (‘org-archive-subtree-default’) - Archive the current entry using the command specified in the - variable ‘org-archive-default-command’. - -* Menu: - -* Moving subtrees:: Moving a tree to an archive file. -* Internal archiving:: Switch off a tree but keep it in the file. - - -File: org.info, Node: Moving subtrees, Next: Internal archiving, Up: Archiving - -9.2.1 Moving a tree to an archive file --------------------------------------- - -The most common archiving action is to move a project tree to another -file, the archive file. - -‘C-c C-x C-s’ or short ‘C-c $’ (‘org-archive-subtree’) - Archive the subtree starting at point position to the location - given by ‘org-archive-location’. - -‘C-u C-c C-x C-s’ - Check if any direct children of the current headline could be moved - to the archive. To do this, check each subtree for open TODO - entries. If none is found, the command offers to move it to the - archive location. If point is _not_ on a headline when this - command is invoked, check level 1 trees. - -‘C-u C-u C-c C-x C-s’ - As above, but check subtree for timestamps instead of TODO entries. - The command offers to archive the subtree if it _does_ contain a - timestamp, and that timestamp is in the past. - - The default archive location is a file in the same directory as the -current file, with the name derived by appending ‘_archive’ to the -current file name. You can also choose what heading to file archived -items under, with the possibility to add them to a datetree in a file. -For information and examples on how to specify the file and the heading, -see the documentation string of the variable ‘org-archive-location’. - - There is also an in-buffer option for setting this variable, for -example: - - #+ARCHIVE: %s_done:: - - If you would like to have a special archive location for a single -entry or a (sub)tree, give the entry an ‘ARCHIVE’ property with the -location as the value (see *note Properties and Columns::). - - When a subtree is moved, it receives a number of special properties -that record context information like the file from where the entry came, -its outline path the archiving time etc. Configure the variable -‘org-archive-save-context-info’ to adjust the amount of information -added. - - When ‘org-archive-subtree-save-file-p’ is non-‘nil’, save the target -archive buffer. - - -File: org.info, Node: Internal archiving, Prev: Moving subtrees, Up: Archiving - -9.2.2 Internal archiving ------------------------- - -If you want to just switch off—for agenda views—certain subtrees without -moving them to a different file, you can use the ‘ARCHIVE’ tag. - - A headline that is marked with the ‘ARCHIVE’ tag (see *note Tags::) -stays at its location in the outline tree, but behaves in the following -way: - - • It does not open when you attempt to do so with a visibility - cycling command (see *note Visibility Cycling::). You can force - cycling archived subtrees with ‘C-<TAB>’, or by setting the option - ‘org-cycle-open-archived-trees’. Also normal outline commands, - like ‘outline-show-all’, open archived subtrees. - - • During sparse tree construction (see *note Sparse Trees::), matches - in archived subtrees are not exposed, unless you configure the - option ‘org-sparse-tree-open-archived-trees’. - - • During agenda view construction (see *note Agenda Views::), the - content of archived trees is ignored unless you configure the - option ‘org-agenda-skip-archived-trees’, in which case these trees - are always included. In the agenda you can press ‘v a’ to get - archives temporarily included. - - • Archived trees are not exported (see *note Exporting::), only the - headline is. Configure the details using the variable - ‘org-export-with-archived-trees’. - - • Archived trees are excluded from column view unless the variable - ‘org-columns-skip-archived-trees’ is configured to ‘nil’. - - The following commands help manage the ‘ARCHIVE’ tag: - -‘C-c C-x a’ (‘org-toggle-archive-tag’) - Toggle the archive tag for the current headline. When the tag is - set, the headline changes to a shadowed face, and the subtree below - it is hidden. - -‘C-u C-c C-x a’ - Check if any direct children of the current headline should be - archived. To do this, check each subtree for open TODO entries. - If none is found, the command offers to set the ‘ARCHIVE’ tag for - the child. If point is _not_ on a headline when this command is - invoked, check the level 1 trees. - -‘C-c C-<TAB>’ (‘org-force-cycle-archived’) - Cycle a tree even if it is tagged with ‘ARCHIVE’. - -‘C-c C-x A’ (‘org-archive-to-archive-sibling’) - Move the current entry to the _Archive Sibling_. This is a sibling - of the entry with the heading ‘Archive’ and the archive tag. The - entry becomes a child of that sibling and in this way retains a lot - of its original context, including inherited tags and approximate - position in the outline. - - -File: org.info, Node: Capture and Attachments, Next: Agenda Views, Prev: Refiling and Archiving, Up: Top - -10 Capture and Attachments -************************** - -An important part of any organization system is the ability to quickly -capture new ideas and tasks, and to associate reference material with -them. Org does this using a process called _capture_. It also can -store files related to a task (_attachments_) in a special directory. -Finally, it can parse RSS feeds for information. To learn how to let -external programs (for example a web browser) trigger Org to capture -material, see *note Protocols::. - -* Menu: - -* Capture:: Capturing new stuff. -* Attachments:: Attach files to outlines. -* RSS Feeds:: Getting input from RSS feeds. - - -File: org.info, Node: Capture, Next: Attachments, Up: Capture and Attachments - -10.1 Capture -============ - -Capture lets you quickly store notes with little interruption of your -work flow. Org’s method for capturing new items is heavily inspired by -John Wiegley’s excellent Remember package. - -* Menu: - -* Setting up capture:: Where notes will be stored. -* Using capture:: Commands to invoke and terminate capture. -* Capture templates:: Define the outline of different note types. - - -File: org.info, Node: Setting up capture, Next: Using capture, Up: Capture - -10.1.1 Setting up capture -------------------------- - -The following customization sets a default target file for notes. - - (setq org-default-notes-file (concat org-directory "/notes.org")) - - You may also define a global key for capturing new material (see -*note Activation::). - - -File: org.info, Node: Using capture, Next: Capture templates, Prev: Setting up capture, Up: Capture - -10.1.2 Using capture --------------------- - -‘M-x org-capture’ (‘org-capture’) - Display the capture templates menu. If you have templates defined - (see *note Capture templates::), it offers these templates for - selection or use a new Org outline node as the default template. - It inserts the template into the target file and switch to an - indirect buffer narrowed to this new node. You may then insert the - information you want. - -‘C-c C-c’ (‘org-capture-finalize’) - Once you have finished entering information into the capture - buffer, ‘C-c C-c’ returns you to the window configuration before - the capture process, so that you can resume your work without - further distraction. When called with a prefix argument, finalize - and then jump to the captured item. - -‘C-c C-w’ (‘org-capture-refile’) - Finalize the capture process by refiling the note to a different - place (see *note Refile and Copy::). Please realize that this is a - normal refiling command that will be executed—so point position at - the moment you run this command is important. If you have inserted - a tree with a parent and children, first move point back to the - parent. Any prefix argument given to this command is passed on to - the ‘org-refile’ command. - -‘C-c C-k’ (‘org-capture-kill’) - Abort the capture process and return to the previous state. - - You can also call ‘org-capture’ in a special way from the agenda, -using the ‘k c’ key combination. With this access, any timestamps -inserted by the selected capture template defaults to the date at point -in the agenda, rather than to the current date. - - To find the locations of the last stored capture, use ‘org-capture’ -with prefix commands: - -‘C-u M-x org-capture’ - Visit the target location of a capture template. You get to select - the template in the usual way. - -‘C-u C-u M-x org-capture’ - Visit the last stored capture item in its buffer. - - You can also jump to the bookmark ‘org-capture-last-stored’, which is -automatically created unless you set ‘org-capture-bookmark’ to ‘nil’. - - To insert the capture at point in an Org buffer, call ‘org-capture’ -with a ‘C-0’ prefix argument. - - -File: org.info, Node: Capture templates, Prev: Using capture, Up: Capture - -10.1.3 Capture templates ------------------------- - -You can use templates for different types of capture items, and for -different target locations. The easiest way to create such templates is -through the customize interface. - -‘C’ - Customize the variable ‘org-capture-templates’. - - Before we give the formal description of template definitions, let’s -look at an example. Say you would like to use one template to create -general TODO entries, and you want to put these entries under the -heading ‘Tasks’ in your file ‘~/org/gtd.org’. Also, a date tree in the -file ‘journal.org’ should capture journal entries. A possible -configuration would look like: - - (setq org-capture-templates - '(("t" "Todo" entry (file+headline "~/org/gtd.org" "Tasks") - "* TODO %?\n %i\n %a") - ("j" "Journal" entry (file+datetree "~/org/journal.org") - "* %?\nEntered on %U\n %i\n %a"))) - - If you then press ‘t’ from the capture menu, Org will prepare the -template for you like this: - - * TODO - [[file:LINK TO WHERE YOU INITIATED CAPTURE]] - -During expansion of the template, ‘%a’ has been replaced by a link to -the location from where you called the capture command. This can be -extremely useful for deriving tasks from emails, for example. You fill -in the task definition, press ‘C-c C-c’ and Org returns you to the same -place where you started the capture process. - - To define special keys to capture to a particular template without -going through the interactive template selection, you can create your -key binding like this: - - (define-key global-map (kbd "C-c x") - (lambda () (interactive) (org-capture nil "x"))) - -* Menu: - -* Template elements:: What is needed for a complete template entry. -* Template expansion:: Filling in information about time and context. -* Templates in contexts:: Only show a template in a specific context. - - -File: org.info, Node: Template elements, Next: Template expansion, Up: Capture templates - -10.1.3.1 Template elements -.......................... - -Now lets look at the elements of a template definition. Each entry in -‘org-capture-templates’ is a list with the following items: - -keys - The keys that selects the template, as a string, characters only, - for example ‘"a"’, for a template to be selected with a single key, - or ‘"bt"’ for selection with two keys. When using several keys, - keys using the same prefix key must be sequential in the list and - preceded by a 2-element entry explaining the prefix key, for - example: - - ("b" "Templates for marking stuff to buy") - - If you do not define a template for the ‘C’ key, this key opens the - Customize buffer for this complex variable. - -description - A short string describing the template, shown during selection. - -type - The type of entry, a symbol. Valid values are: - - ‘entry’ - An Org mode node, with a headline. Will be filed as the child - of the target entry or as a top-level entry. The target file - should be an Org file. - - ‘item’ - A plain list item, placed in the first plain list at the - target location. Again the target file should be an Org file. - - ‘checkitem’ - A checkbox item. This only differs from the plain list item - by the default template. - - ‘table-line’ - A new line in the first table at the target location. Where - exactly the line will be inserted depends on the properties - ‘:prepend’ and ‘:table-line-pos’ (see below). - - ‘plain’ - Text to be inserted as it is. - -target - Specification of where the captured item should be placed. In Org - files, targets usually define a node. Entries will become children - of this node. Other types will be added to the table or list in - the body of this node. Most target specifications contain a file - name. If that file name is the empty string, it defaults to - ‘org-default-notes-file’. A file can also be given as a variable - or as a function called with no argument. When an absolute path is - not specified for a target, it is taken as relative to - ‘org-directory’. - - Valid values are: - - ‘(file "path/to/file")’ - Text will be placed at the beginning or end of that file. - - ‘(id "id of existing org entry")’ - Filing as child of this entry, or in the body of the entry. - - ‘(file+headline "filename" "node headline")’ - Fast configuration if the target heading is unique in the - file. - - ‘(file+olp "filename" "Level 1 heading" "Level 2" ...)’ - For non-unique headings, the full path is safer. - - ‘(file+regexp "filename" "regexp to find location")’ - Use a regular expression to position point. - - ‘(file+olp+datetree "filename" [ "Level 1 heading" ...])’ - This target(1) creates a heading in a date tree(2) for today’s - date. If the optional outline path is given, the tree will be - built under the node it is pointing to, instead of at top - level. Check out the ‘:time-prompt’ and ‘:tree-type’ - properties below for additional options. - - ‘(file+function "filename" function-finding-location)’ - A function to find the right location in the file. - - ‘(clock)’ - File to the entry that is currently being clocked. - - ‘(function function-finding-location)’ - Most general way: write your own function which both visits - the file and moves point to the right location. - -template - The template for creating the capture item. If you leave this - empty, an appropriate default template will be used. Otherwise - this is a string with escape codes, which will be replaced - depending on time and context of the capture call. You may also - get this template string from a file(3), or dynamically, from a - function using either syntax: - - (file "/path/to/template-file") - (function FUNCTION-RETURNING-THE-TEMPLATE) - -properties - The rest of the entry is a property list of additional options. - Recognized properties are: - - ‘:prepend’ - Normally new captured information will be appended at the - target location (last child, last table line, last list item, - ...). Setting this property changes that. - - ‘:immediate-finish’ - When set, do not offer to edit the information, just file it - away immediately. This makes sense if the template only needs - information that can be added automatically. - - ‘:jump-to-captured’ - When set, jump to the captured entry when finished. - - ‘:empty-lines’ - Set this to the number of lines to insert before and after the - new item. Default 0, and the only other common value is 1. - - ‘:empty-lines-after’ - Set this to the number of lines that should be inserted after - the new item. Overrides ‘:empty-lines’ for the number of - lines inserted after. - - ‘:empty-lines-before’ - Set this to the number of lines that should be inserted before - the new item. Overrides ‘:empty-lines’ for the number lines - inserted before. - - ‘:clock-in’ - Start the clock in this item. - - ‘:clock-keep’ - Keep the clock running when filing the captured entry. - - ‘:clock-resume’ - If starting the capture interrupted a clock, restart that - clock when finished with the capture. Note that ‘:clock-keep’ - has precedence over ‘:clock-resume’. When setting both to - non-‘nil’, the current clock will run and the previous one - will not be resumed. - - ‘:time-prompt’ - Prompt for a date/time to be used for date/week trees and when - filling the template. Without this property, capture uses the - current date and time. Even if this property has not been - set, you can force the same behavior by calling ‘org-capture’ - with a ‘C-1’ prefix argument. - - ‘:tree-type’ - Use ‘week’ to make a week tree instead of the month-day tree, - i.e., place the headings for each day under a heading with the - current ISO week. Use ‘month’ to group entries by month only. - Default is to group entries by day. - - ‘:unnarrowed’ - Do not narrow the target buffer, simply show the full buffer. - Default is to narrow it so that you only see the new material. - - ‘:table-line-pos’ - Specification of the location in the table where the new line - should be inserted. It should be a string like ‘II-3’ meaning - that the new line should become the third line before the - second horizontal separator line. - - ‘:kill-buffer’ - If the target file was not yet visited when capture was - invoked, kill the buffer again after capture is completed. - - ‘:no-save’ - Do not save the target file after finishing the capture. - - ~:refile-targets - Temporarily set ‘org-refile-targets’ to the value of this - property. - - ---------- Footnotes ---------- - - (1) Org used to offer four different targets for date/week tree -capture. Now, Org automatically translates these to use -‘file+olp+datetree’, applying the ‘:time-prompt’ and ‘:tree-type’ -properties. Please rewrite your date/week-tree targets using -‘file+olp+datetree’ since the older targets are now deprecated. - - (2) A date tree is an outline structure with years on the highest -level, months or ISO weeks as sublevels and then dates on the lowest -level. Tags are allowed in the tree structure. - - (3) When the file name is not absolute, Org assumes it is relative to -‘org-directory’. - - -File: org.info, Node: Template expansion, Next: Templates in contexts, Prev: Template elements, Up: Capture templates - -10.1.3.2 Template expansion -........................... - -In the template itself, special “%-escapes”(1) allow dynamic insertion -of content. The templates are expanded in the order given here: - -‘%[FILE]’ - Insert the contents of the file given by FILE. - -‘%(EXP)’ - Evaluate Elisp expression EXP and replace it with the result. The - EXP form must return a string. Only placeholders pre-existing - within the template, or introduced with ‘%[file]’, are expanded - this way. Since this happens after expanding non-interactive - “%-escapes”, those can be used to fill the expression. - -‘%<FORMAT>’ - The result of format-time-string on the FORMAT specification. - -‘%t’ - Timestamp, date only. - -‘%T’ - Timestamp, with date and time. - -‘%u’, ‘%U’ - Like ‘%t’, ‘%T’ above, but inactive timestamps. - -‘%i’ - Initial content, the region when capture is called while the region - is active. If there is text before ‘%i’ on the same line, such as - indentation, and ‘%i’ is not inside a ‘%(exp)’ form, that prefix is - added before every line in the inserted text. - -‘%a’ - Annotation, normally the link created with ‘org-store-link’. - -‘%A’ - Like ‘%a’, but prompt for the description part. - -‘%l’ - Like ‘%a’, but only insert the literal link. - -‘%L’ - Like ‘%l’, but without brackets (the link content itself). - -‘%c’ - Current kill ring head. - -‘%x’ - Content of the X clipboard. - -‘%k’ - Title of the currently clocked task. - -‘%K’ - Link to the currently clocked task. - -‘%n’ - User name (taken from ‘user-full-name’). - -‘%f’ - File visited by current buffer when org-capture was called. - -‘%F’ - Full path of the file or directory visited by current buffer. - -‘%:keyword’ - Specific information for certain link types, see below. - -‘%^g’ - Prompt for tags, with completion on tags in target file. - -‘%^G’ - Prompt for tags, with completion all tags in all agenda files. - -‘%^t’ - Like ‘%t’, but prompt for date. Similarly ‘%^T’, ‘%^u’, ‘%^U’. - You may define a prompt like ‘%^{Birthday}t’. - -‘%^C’ - Interactive selection of which kill or clip to use. - -‘%^L’ - Like ‘%^C’, but insert as link. - -‘%^{PROP}p’ - Prompt the user for a value for property PROP. You may specify a - default value with ‘%^{PROP|default}’. - -‘%^{PROMPT}’ - Prompt the user for a string and replace this sequence with it. - You may specify a default value and a completion table with - ‘%^{prompt|default|completion2|completion3...}’. The arrow keys - access a prompt-specific history. - -‘%\N’ - Insert the text entered at the Nth ‘%^{PROMPT}’, where N is a - number, starting from 1. - -‘%?’ - After completing the template, position point here. - - For specific link types, the following keywords are defined(2): - -Link type Available keywords --------------------------------------------------------------------------- -bbdb ‘%:name’, ‘%:company’ -irc ‘%:server’, ‘%:port’, ‘%:nick’ -mh, rmail ‘%:type’, ‘%:subject’, ‘%:message-id’ - ‘%:from’, ‘%:fromname’, ‘%:fromaddress’ - ‘%:to’, ‘%:toname’, ‘%:toaddress’ - ‘%:date’ (message date header field) - ‘%:date-timestamp’ (date as active timestamp) - ‘%:date-timestamp-inactive’ (date as inactive timestamp) - ‘%:fromto’ (either “to NAME” or “from NAME”)(3) -gnus ‘%:group’, for messages also all email fields -w3, w3m ‘%:url’ -info ‘%:file’, ‘%:node’ -calendar ‘%:date’ -org-protocol ‘%:link’, ‘%:description’, ‘%:annotation’ - - ---------- Footnotes ---------- - - (1) If you need one of these sequences literally, escape the ‘%’ with -a backslash. - - (2) If you define your own link types (see *note Adding Hyperlink -Types::), any property you store with ‘org-store-link-props’ can be -accessed in capture templates in a similar way. - - (3) This is always the other, not the user. See the variable -‘org-link-from-user-regexp’. - - -File: org.info, Node: Templates in contexts, Prev: Template expansion, Up: Capture templates - -10.1.3.3 Templates in contexts -.............................. - -To control whether a capture template should be accessible from a -specific context, you can customize ‘org-capture-templates-contexts’. -Let’s say, for example, that you have a capture template “p” for storing -Gnus emails containing patches. Then you would configure this option -like this: - - (setq org-capture-templates-contexts - '(("p" ((in-mode . "message-mode"))))) - - You can also tell that the command key ‘p’ should refer to another -template. In that case, add this command key like this: - - (setq org-capture-templates-contexts - '(("p" "q" ((in-mode . "message-mode"))))) - - See the docstring of the variable for more information. - - -File: org.info, Node: Attachments, Next: RSS Feeds, Prev: Capture, Up: Capture and Attachments - -10.2 Attachments -================ - -It is often useful to associate reference material with an outline node. -Small chunks of plain text can simply be stored in the subtree of a -project. Hyperlinks (see *note Hyperlinks::) can establish associations -with files that live elsewhere on a local, or even remote, computer, -like emails or source code files belonging to a project. - - Another method is _attachments_, which are files located in a -directory belonging to an outline node. Org uses directories either -named by a unique ID of each entry, or by a ‘DIR’ property. - -* Menu: - -* Attachment defaults and dispatcher:: How to access attachment commands -* Attachment options:: Configuring the attachment system -* Attachment links:: Hyperlink access to attachments -* Automatic version-control with Git:: Everything safely stored away -* Attach from Dired:: Using dired to select an attachment - - -File: org.info, Node: Attachment defaults and dispatcher, Next: Attachment options, Up: Attachments - -10.2.1 Attachment defaults and dispatcher ------------------------------------------ - -By default, Org attach uses ID properties when adding attachments to -outline nodes. This makes working with attachments fully automated. -There is no decision needed for folder-name or location. ID-based -directories are by default located in the ‘data/’ directory, which lives -in the same directory where your Org file lives(1). - - When attachments are made using ‘org-attach’ a default tag ‘ATTACH’ -is added to the node that gets the attachments. - - For more control over the setup, see *note Attachment options::. - - The following commands deal with attachments: - -‘C-c C-a’ (‘org-attach’) - The dispatcher for commands related to the attachment system. - After these keys, a list of commands is displayed and you must - press an additional key to select a command: - - ‘a’ (‘org-attach-attach’) - Select a file and move it into the task’s attachment - directory. The file is copied, moved, or linked, depending on - ‘org-attach-method’. Note that hard links are not supported - on all systems. - - ‘c’/‘m’/‘l’ - Attach a file using the copy/move/link method. Note that hard - links are not supported on all systems. - - ‘b’ (‘org-attach-buffer’) - Select a buffer and save it as a file in the task’s attachment - directory. - - ‘n’ (‘org-attach-new’) - Create a new attachment as an Emacs buffer. - - ‘z’ (‘org-attach-sync’) - Synchronize the current task with its attachment directory, in - case you added attachments yourself. - - ‘o’ (‘org-attach-open’) - Open current task’s attachment. If there is more than one, - prompt for a file name first. Opening follows the rules set - by ‘org-file-apps’. For more details, see the information on - following hyperlinks (see *note Handling Links::). - - ‘O’ (‘org-attach-open-in-emacs’) - Also open the attachment, but force opening the file in Emacs. - - ‘f’ (‘org-attach-reveal’) - Open the current task’s attachment directory. - - ‘F’ (‘org-attach-reveal-in-emacs’) - Also open the directory, but force using Dired in Emacs. - - ‘d’ (‘org-attach-delete-one’) - Select and delete a single attachment. - - ‘D’ (‘org-attach-delete-all’) - Delete all of a task’s attachments. A safer way is to open - the directory in Dired and delete from there. - - ‘s’ (‘org-attach-set-directory’) - Set a specific directory as the entry’s attachment directory. - This works by putting the directory path into the ‘DIR’ - property. - - ‘S’ (‘org-attach-unset-directory’) - Remove the attachment directory. This command removes the - ‘DIR’ property and asks the user to either move content inside - that folder, if an ‘ID’ property is set, delete the content, - or to leave the attachment directory as is but no longer - attached to the outline node. - - ---------- Footnotes ---------- - - (1) If you move entries or Org files from one directory to another, -you may want to configure ‘org-attach-id-dir’ to contain an absolute -path. - - -File: org.info, Node: Attachment options, Next: Attachment links, Prev: Attachment defaults and dispatcher, Up: Attachments - -10.2.2 Attachment options -------------------------- - -There are a couple of options for attachments that are worth mentioning. - -‘org-attach-id-dir’ - The directory where attachments are stored when ‘ID’ is used as - method. - -‘org-attach-dir-relative’ - When setting the ‘DIR’ property on a node using ‘C-c C-a s’ - (‘org-attach-set-directory’), absolute links are entered by - default. This option changes that to relative links. - -‘org-attach-use-inheritance’ - By default folders attached to an outline node are inherited from - parents according to ‘org-use-property-inheritance’. If one - instead want to set inheritance specifically for Org attach that - can be done using ‘org-attach-use-inheritance’. Inheriting - documents through the node hierarchy makes a lot of sense in most - cases. Especially when using attachment links (see *note - Attachment links::). The following example shows one use case for - attachment inheritance: - - * Chapter A ... - :PROPERTIES: - :DIR: Chapter A/ - :END: - ** Introduction - Some text - - #+NAME: Image 1 - [[attachment:image 1.jpg]] - - Without inheritance one would not be able to resolve the link to - ‘image 1.jpg’, since the link is inside a sub-heading to ‘Chapter - A’. - - Inheritance works the same way for both ‘ID’ and ‘DIR’ property. - If both properties are defined on the same headline then ‘DIR’ - takes precedence. This is also true if inheritance is enabled. If - ‘DIR’ is inherited from a parent node in the outline, that property - still takes precedence over an ‘ID’ property defined on the node - itself. - -‘org-attach-method’ - When attaching files using the dispatcher ‘C-c C-a’ it defaults to - copying files. The behavior can be changed by customizing - ‘org-attach-method’. Options are Copy, Move/Rename, Hard link or - Symbolic link. - -‘org-attach-preferred-new-method’ - This customization lets you choose the default way to attach to - nodes without existing ‘ID’ and ‘DIR’ property. It defaults to - ‘id’ but can also be set to ‘dir’, ‘ask’ or ‘nil’. - -‘org-attach-archive-delete’ - Configure this to determine if attachments should be deleted or not - when a subtree that has attachments is archived. - -‘org-attach-auto-tag’ - When attaching files to a heading it will be assigned a tag - according to what is set here. - -‘org-attach-id-to-path-function-list’ - When ‘ID’ is used for attachments, the ID is parsed into a part of - a directory-path. See ‘org-attach-id-uuid-folder-format’ for the - default function. Define a new one and add it as first element in - ‘org-attach-id-to-path-function-list’ if you want the folder - structure in any other way. All functions in this list will be - tried when resolving existing ID’s into paths, to maintain backward - compatibility with existing folders in your system. - -‘org-attach-store-link-p’ - Stores a link to the file that is being attached. The link is - stored in ‘org-stored-links’ for later insertion with ‘C-c C-l’ - (see *note Handling Links::). Depending on what option is set in - ‘org-attach-store-link-p’, the link is stored to either the - original location as a file link, the attachment location as an - attachment link or to the attachment location as a file link. - -‘org-attach-commands’ - List of all commands used in the attach dispatcher. - -‘org-attach-expert’ - Do not show the splash buffer with the attach dispatcher when - ‘org-attach-expert’ is set to non-‘nil’. - - See customization group ‘Org Attach’ if you want to change the -default settings. - - -File: org.info, Node: Attachment links, Next: Automatic version-control with Git, Prev: Attachment options, Up: Attachments - -10.2.3 Attachment links ------------------------ - -Attached files and folders can be referenced using attachment links. -This makes it easy to refer to the material added to an outline node. -Especially if it was attached using the unique ID of the entry! - - * TODO Some task - :PROPERTIES: - :ID: 95d50008-c12e-479f-a4f2-cc0238205319 - :END: - See attached document for more information: [[attachment:info.org]] - - See *note External Links:: for more information about these links. - - -File: org.info, Node: Automatic version-control with Git, Next: Attach from Dired, Prev: Attachment links, Up: Attachments - -10.2.4 Automatic version-control with Git ------------------------------------------ - -If the directory attached to an outline node is a Git repository, Org -can be configured to automatically commit changes to that repository -when it sees them. - - To make Org mode take care of versioning of attachments for you, add -the following to your Emacs config: - - (require 'org-attach-git) - - -File: org.info, Node: Attach from Dired, Prev: Automatic version-control with Git, Up: Attachments - -10.2.5 Attach from Dired ------------------------- - -It is possible to attach files to a subtree from a Dired buffer. To use -this feature, have one window in Dired mode containing the file(s) to be -attached and another window with point in the subtree that shall get the -attachments. In the Dired window, with point on a file, ‘M-x -org-attach-dired-to-subtree’ attaches the file to the subtree using the -attachment method set by variable ‘org-attach-method’. When files are -marked in the Dired window then all marked files get attached. - - Add the following lines to the Emacs init file to have ‘C-c C-x a’ -attach files in Dired buffers. - - (add-hook 'dired-mode-hook - (lambda () - (define-key dired-mode-map - (kbd "C-c C-x a") - #'org-attach-dired-to-subtree))) - - The following code shows how to bind the previous command with a -specific attachment method. - - (add-hook 'dired-mode-hook - (lambda () - (define-key dired-mode-map (kbd "C-c C-x c") - (lambda () - (interactive) - (let ((org-attach-method 'cp)) - (call-interactively #'org-attach-dired-to-subtree)))))) - - -File: org.info, Node: RSS Feeds, Prev: Attachments, Up: Capture and Attachments - -10.3 RSS Feeds -============== - -Org can add and change entries based on information found in RSS feeds -and Atom feeds. You could use this to make a task out of each new -podcast in a podcast feed. Or you could use a phone-based note-creating -service on the web to import tasks into Org. To access feeds, configure -the variable ‘org-feed-alist’. The docstring of this variable has -detailed information. With the following - - (setq org-feed-alist - '(("Slashdot" - "https://rss.slashdot.org/Slashdot/slashdot" - "~/txt/org/feeds.org" "Slashdot Entries"))) - -new items from the feed provided by ‘rss.slashdot.org’ result in new -entries in the file ‘~/org/feeds.org’ under the heading ‘Slashdot -Entries’, whenever the following command is used: - -‘C-c C-x g’ (‘org-feed-update-all’) - Collect items from the feeds configured in ‘org-feed-alist’ and act - upon them. - -‘C-c C-x G’ (‘org-feed-goto-inbox’) - Prompt for a feed name and go to the inbox configured for this - feed. - - Under the same headline, Org creates a drawer ‘FEEDSTATUS’ in which -it stores information about the status of items in the feed, to avoid -adding the same item several times. - - For more information, including how to read atom feeds, see -‘org-feed.el’ and the docstring of ‘org-feed-alist’. - - -File: org.info, Node: Agenda Views, Next: Markup for Rich Contents, Prev: Capture and Attachments, Up: Top - -11 Agenda Views -*************** - -Due to the way Org works, TODO items, time-stamped items, and tagged -headlines can be scattered throughout a file or even a number of files. -To get an overview of open action items, or of events that are important -for a particular date, this information must be collected, sorted and -displayed in an organized way. - - Org can select items based on various criteria and display them in a -separate buffer. Six different view types are provided: - - • an _agenda_ that is like a calendar and shows information for - specific dates, - - • a _TODO list_ that covers all unfinished action items, - - • a _match view_, showings headlines based on the tags, properties, - and TODO state associated with them, - - • a _text search view_ that shows all entries from multiple files - that contain specified keywords, - - • a _stuck projects view_ showing projects that currently do not move - along, and - - • _custom views_ that are special searches and combinations of - different views. - - The extracted information is displayed in a special _agenda buffer_. -This buffer is read-only, but provides commands to visit the -corresponding locations in the original Org files, and even to edit -these files remotely. - - By default, the report ignores commented (see *note Comment Lines::) -and archived (see *note Internal archiving::) entries. You can override -this by setting ‘org-agenda-skip-comment-trees’ and -‘org-agenda-skip-archived-trees’ to ‘nil’. - - Two variables control how the agenda buffer is displayed and whether -the window configuration is restored when the agenda exits: -‘org-agenda-window-setup’ and ‘org-agenda-restore-windows-after-quit’. - -* Menu: - -* Agenda Files:: Files being searched for agenda information. -* Agenda Dispatcher:: Keyboard access to agenda views. -* Built-in Agenda Views:: What is available out of the box? -* Presentation and Sorting:: How agenda items are prepared for display. -* Agenda Commands:: Remote editing of Org trees. -* Custom Agenda Views:: Defining special searches and views. -* Exporting Agenda Views:: Writing a view to a file. -* Agenda Column View:: Using column view for collected entries. - - -File: org.info, Node: Agenda Files, Next: Agenda Dispatcher, Up: Agenda Views - -11.1 Agenda Files -================= - -The information to be shown is normally collected from all _agenda -files_, the files listed in the variable ‘org-agenda-files’(1). If a -directory is part of this list, all files with the extension ‘.org’ in -this directory are part of the list. - - Thus, even if you only work with a single Org file, that file should -be put into the list(2). You can customize ‘org-agenda-files’, but the -easiest way to maintain it is through the following commands - -‘C-c [’ (‘org-agenda-file-to-front’) - Add current file to the list of agenda files. The file is added to - the front of the list. If it was already in the list, it is moved - to the front. With a prefix argument, file is added/moved to the - end. - -‘C-c ]’ (‘org-remove-file’) - Remove current file from the list of agenda files. - -‘C-'’ -‘C-,’ (‘org-cycle-agenda-files’) - Cycle through agenda file list, visiting one file after the other. - -‘M-x org-switchb’ - Command to use an Iswitchb-like interface to switch to and between - Org buffers. - -The Org menu contains the current list of files and can be used to visit -any of them. - - If you would like to focus the agenda temporarily on a file not in -this list, or on just one file in the list, or even on only a subtree in -a file, then this can be done in different ways. For a single agenda -command, you may press ‘<’ once or several times in the dispatcher (see -*note Agenda Dispatcher::). To restrict the agenda scope for an -extended period, use the following commands: - -‘C-c C-x <’ (‘org-agenda-set-restriction-lock’) - Restrict the agenda to the current subtree. If there already is a - restriction at point, remove it. When called with a universal - prefix argument or with point before the first headline in a file, - set the agenda scope to the entire file. This restriction remains - in effect until removed with ‘C-c C-x >’, or by typing either ‘<’ - or ‘>’ in the agenda dispatcher. If there is a window displaying - an agenda view, the new restriction takes effect immediately. - -‘C-c C-x >’ (‘org-agenda-remove-restriction-lock’) - Remove the restriction created by ‘C-c C-x <’. - - When working with Speedbar, you can use the following commands in the -Speedbar frame: - -‘<’ (‘org-speedbar-set-agenda-restriction’) - Restrict the agenda to the item—either an Org file or a subtree in - such a file—at point in the Speedbar frame. If agenda is already - restricted there, remove the restriction. If there is a window - displaying an agenda view, the new restriction takes effect - immediately. - -‘>’ (‘org-agenda-remove-restriction-lock’) - Remove the restriction. - - ---------- Footnotes ---------- - - (1) If the value of that variable is not a list, but a single file -name, then the list of agenda files in maintained in that external file. - - (2) When using the dispatcher, pressing ‘<’ before selecting a -command actually limits the command to the current file, and ignores -‘org-agenda-files’ until the next dispatcher command. - - -File: org.info, Node: Agenda Dispatcher, Next: Built-in Agenda Views, Prev: Agenda Files, Up: Agenda Views - -11.2 The Agenda Dispatcher -========================== - -The views are created through a dispatcher, accessible with ‘M-x -org-agenda’, or, better, bound to a global key (see *note Activation::). -It displays a menu from which an additional letter is required to -execute a command. The dispatcher offers the following default -commands: - -‘a’ - Create the calendar-like agenda (see *note Weekly/daily agenda::). - -‘t’ -‘T’ - Create a list of all TODO items (see *note Global TODO list::). - -‘m’ -‘M’ - Create a list of headlines matching a given expression (see *note - Matching tags and properties::). - -‘s’ - Create a list of entries selected by a boolean expression of - keywords and/or regular expressions that must or must not occur in - the entry. - -‘/’ - Search for a regular expression in all agenda files and - additionally in the files listed in - ‘org-agenda-text-search-extra-files’. This uses the Emacs command - ‘multi-occur’. A prefix argument can be used to specify the number - of context lines for each match, default is - 1. -‘#’ - Create a list of stuck projects (see *note Stuck projects::). - -‘!’ - Configure the list of stuck projects (see *note Stuck projects::). - -‘<’ - Restrict an agenda command to the current buffer(1). If narrowing - is in effect restrict to the narrowed part of the buffer. After - pressing ‘<’, you still need to press the character selecting the - command. - -‘< <’ - If there is an active region, restrict the following agenda command - to the region. Otherwise, restrict it to the current subtree(2). - After pressing ‘< <’, you still need to press the character - selecting the command. - -‘*’ - Toggle sticky agenda views. By default, Org maintains only a - single agenda buffer and rebuilds it each time you change the view, - to make sure everything is always up to date. If you switch - between views often and the build time bothers you, you can turn on - sticky agenda buffers (make this the default by customizing the - variable ‘org-agenda-sticky’). With sticky agendas, the dispatcher - only switches to the selected view, you need to update it by hand - with ‘r’ or ‘g’. You can toggle sticky agenda view any time with - ‘org-toggle-sticky-agenda’. - - You can also define custom commands that are accessible through the -dispatcher, just like the default commands. This includes the -possibility to create extended agenda buffers that contain several -blocks together, for example the weekly agenda, the global TODO list and -a number of special tags matches. See *note Custom Agenda Views::. - - ---------- Footnotes ---------- - - (1) For backward compatibility, you can also press ‘1’ to restrict to -the current buffer. - - (2) For backward compatibility, you can also press ‘0’ to restrict to -the current region/subtree. - - -File: org.info, Node: Built-in Agenda Views, Next: Presentation and Sorting, Prev: Agenda Dispatcher, Up: Agenda Views - -11.3 The Built-in Agenda Views -============================== - -In this section we describe the built-in views. - -* Menu: - -* Weekly/daily agenda:: The calendar page with current tasks. -* Global TODO list:: All unfinished action items. -* Matching tags and properties:: Structured information with fine-tuned search. -* Search view:: Find entries by searching for text. -* Stuck projects:: Find projects you need to review. - - -File: org.info, Node: Weekly/daily agenda, Next: Global TODO list, Up: Built-in Agenda Views - -11.3.1 Weekly/daily agenda --------------------------- - -The purpose of the weekly/daily _agenda_ is to act like a page of a -paper agenda, showing all the tasks for the current week or day. - -‘M-x org-agenda a’ (‘org-agenda-list’) - Compile an agenda for the current week from a list of Org files. - The agenda shows the entries for each day. With a numeric prefix - argument(1)—like ‘C-u 2 1 M-x org-agenda a’—you may set the number - of days to be displayed. - - The default number of days displayed in the agenda is set by the -variable ‘org-agenda-span’. This variable can be set to any number of -days you want to see by default in the agenda, or to a span name, such a -‘day’, ‘week’, ‘month’ or ‘year’. For weekly agendas, the default is to -start on the previous Monday (see ‘org-agenda-start-on-weekday’). You -can also set the start date using a date shift: ‘(setq -org-agenda-start-day "+10d")’ starts the agenda ten days from today in -the future. - - Remote editing from the agenda buffer means, for example, that you -can change the dates of deadlines and appointments from the agenda -buffer. The commands available in the Agenda buffer are listed in *note -Agenda Commands::. - -Calendar/Diary integration -.......................... - -Emacs contains the calendar and diary by Edward M. Reingold. The -calendar displays a three-month calendar with holidays from different -countries and cultures. The diary allows you to keep track of -anniversaries, lunar phases, sunrise/set, recurrent appointments -(weekly, monthly) and more. In this way, it is quite complementary to -Org. It can be very useful to combine output from Org with the diary. - - In order to include entries from the Emacs diary into Org mode’s -agenda, you only need to customize the variable - - (setq org-agenda-include-diary t) - -After that, everything happens automatically. All diary entries -including holidays, anniversaries, etc., are included in the agenda -buffer created by Org mode. ‘<SPC>’, ‘<TAB>’, and ‘<RET>’ can be used -from the agenda buffer to jump to the diary file in order to edit -existing diary entries. The ‘i’ command to insert new entries for the -current date works in the agenda buffer, as well as the commands ‘S’, -‘M’, and ‘C’ to display Sunrise/Sunset times, show lunar phases and to -convert to other calendars, respectively. ‘c’ can be used to switch -back and forth between calendar and agenda. - - If you are using the diary only for expression entries and holidays, -it is faster to not use the above setting, but instead to copy or even -move the entries into an Org file. Org mode evaluates diary-style -expression entries, and does it faster because there is no overhead for -first creating the diary display. Note that the expression entries must -start at the left margin, no whitespace is allowed before them, as seen -in the following segment of an Org file:(2) - - * Holidays - :PROPERTIES: - :CATEGORY: Holiday - :END: - %%(org-calendar-holiday) ; special function for holiday names - - * Birthdays - :PROPERTIES: - :CATEGORY: Ann - :END: - %%(org-anniversary 1956 5 14) Arthur Dent is %d years old - %%(org-anniversary 1869 10 2) Mahatma Gandhi would be %d years old - -Anniversaries from BBDB -....................... - -If you are using the Insidious Big Brother Database to store your -contacts, you very likely prefer to store anniversaries in BBDB rather -than in a separate Org or diary file. Org supports this and can show -BBDB anniversaries as part of the agenda. All you need to do is to add -the following to one of your agenda files: - - * Anniversaries - :PROPERTIES: - :CATEGORY: Anniv - :END: - %%(org-bbdb-anniversaries) - - You can then go ahead and define anniversaries for a BBDB record. -Basically, you need a field named ‘anniversary’ for the BBDB record -which contains the date in the format ‘YYYY-MM-DD’ or ‘MM-DD’, followed -by a space and the class of the anniversary (‘birthday’, ‘wedding’, or a -format string). If you omit the class, it defaults to ‘birthday’. Here -are a few examples, the header for the file ‘ol-bbdb.el’ contains more -detailed information. - - 1973-06-22 - 06-22 - 1955-08-02 wedding - 2008-04-14 %s released version 6.01 of Org mode, %d years ago - - After a change to BBDB, or for the first agenda display during an -Emacs session, the agenda display suffers a short delay as Org updates -its hash with anniversaries. However, from then on things will be very -fast, much faster in fact than a long list of ‘%%(diary-anniversary)’ -entries in an Org or Diary file. - - If you would like to see upcoming anniversaries with a bit of -forewarning, you can use the following instead: - - * Anniversaries - :PROPERTIES: - :CATEGORY: Anniv - :END: - %%(org-bbdb-anniversaries-future 3) - - That will give you three days’ warning: on the anniversary date -itself and the two days prior. The argument is optional: if omitted, it -defaults to 7. - -Appointment reminders -..................... - -Org can interact with Emacs appointments notification facility. To add -the appointments of your agenda files, use the command -‘org-agenda-to-appt’. This command lets you filter through the list of -your appointments and add only those belonging to a specific category or -matching a regular expression. It also reads a ‘APPT_WARNTIME’ property -which overrides the value of ‘appt-message-warning-time’ for this -appointment. See the docstring for details. - - ---------- Footnotes ---------- - - (1) For backward compatibility, the universal prefix argument ‘C-u’ -causes all TODO entries to be listed before the agenda. This feature is -deprecated, use the dedicated TODO list, or a block agenda instead (see -*note Block agenda::). - - (2) The variable ‘org-anniversary’ used in the example is just like -‘diary-anniversary’, but the argument order is always according to ISO -and therefore independent of the value of ‘calendar-date-style’. - - -File: org.info, Node: Global TODO list, Next: Matching tags and properties, Prev: Weekly/daily agenda, Up: Built-in Agenda Views - -11.3.2 The global TODO list ---------------------------- - -The global TODO list contains all unfinished TODO items formatted and -collected into a single place. - -‘M-x org-agenda t’ (‘org-todo-list’) - Show the global TODO list. This collects the TODO items from all - agenda files (see *note Agenda Views::) into a single buffer. By - default, this lists items with a state the is not a DONE state. - The buffer is in Agenda mode, so there are commands to examine and - manipulate the TODO entries directly from that buffer (see *note - Agenda Commands::). - -‘M-x org-agenda T’ (‘org-todo-list’) - Like the above, but allows selection of a specific TODO keyword. - You can also do this by specifying a prefix argument to ‘t’. You - are prompted for a keyword, and you may also specify several - keywords by separating them with ‘|’ as the boolean OR operator. - With a numeric prefix, the Nth keyword in ‘org-todo-keywords’ is - selected. - - The ‘r’ key in the agenda buffer regenerates it, and you can give a - prefix argument to this command to change the selected TODO - keyword, for example ‘3 r’. If you often need a search for a - specific keyword, define a custom command for it (see *note Agenda - Dispatcher::). - - Matching specific TODO keywords can also be done as part of a tags - search (see *note Tag Searches::). - - Remote editing of TODO items means that you can change the state of a -TODO entry with a single key press. The commands available in the TODO -list are described in *note Agenda Commands::. - - Normally the global TODO list simply shows all headlines with TODO -keywords. This list can become very long. There are two ways to keep -it more compact: - - • Some people view a TODO item that has been _scheduled_ for - execution or have a _deadline_ (see *note Timestamps::) as no - longer _open_. Configure the variables - ‘org-agenda-todo-ignore-scheduled’ to exclude some or all scheduled - items from the global TODO list, ‘org-agenda-todo-ignore-deadlines’ - to exclude some or all items with a deadline set, - ‘org-agenda-todo-ignore-timestamp’ to exclude some or all items - with an active timestamp other than a DEADLINE or a SCHEDULED - timestamp and/or ‘org-agenda-todo-ignore-with-date’ to exclude - items with at least one active timestamp. - - • TODO items may have sublevels to break up the task into subtasks. - In such cases it may be enough to list only the highest level TODO - headline and omit the sublevels from the global list. Configure - the variable ‘org-agenda-todo-list-sublevels’ to get this behavior. - - -File: org.info, Node: Matching tags and properties, Next: Search view, Prev: Global TODO list, Up: Built-in Agenda Views - -11.3.3 Matching tags and properties ------------------------------------ - -If headlines in the agenda files are marked with _tags_ (see *note -Tags::), or have properties (see *note Properties and Columns::), you -can select headlines based on this metadata and collect them into an -agenda buffer. The match syntax described here also applies when -creating sparse trees with ‘C-c / m’. - -‘M-x org-agenda m’ (‘org-tags-view’) - Produce a list of all headlines that match a given set of tags. - The command prompts for a selection criterion, which is a boolean - logic expression with tags, like ‘+work+urgent-withboss’ or - ‘work|home’ (see *note Tags::). If you often need a specific - search, define a custom command for it (see *note Agenda - Dispatcher::). - -‘M-x org-agenda M’ (‘org-tags-view’) - Like ‘m’, but only select headlines that are also TODO items and - force checking subitems (see the variable - ‘org-tags-match-list-sublevels’). To exclude scheduled/deadline - items, see the variable - ‘org-agenda-tags-todo-honor-ignore-options’. Matching specific - TODO keywords together with a tags match is also possible, see - *note Tag Searches::. - - The commands available in the tags list are described in *note Agenda -Commands::. - - A search string can use Boolean operators ‘&’ for AND and ‘|’ for OR. -‘&’ binds more strongly than ‘|’. Parentheses are currently not -implemented. Each element in the search is either a tag, a regular -expression matching tags, or an expression like ‘PROPERTY OPERATOR -VALUE’ with a comparison operator, accessing a property value. Each -element may be preceded by ‘-’ to select against it, and ‘+’ is -syntactic sugar for positive selection. The AND operator ‘&’ is -optional when ‘+’ or ‘-’ is present. Here are some examples, using only -tags. - -‘+work-boss’ - Select headlines tagged ‘work’, but discard those also tagged - ‘boss’. - -‘work|laptop’ - Selects lines tagged ‘work’ or ‘laptop’. - -‘work|laptop+night’ - Like before, but require the ‘laptop’ lines to be tagged also - ‘night’. - - Instead of a tag, you may also specify a regular expression enclosed -in curly braces (see *note Regular Expressions::). For example, -‘work+{^boss.*}’ matches headlines that contain the tag ‘:work:’ and any -tag _starting_ with ‘boss’. - - Group tags (see *note Tag Hierarchy::) are expanded as regular -expressions. E.g., if ‘work’ is a group tag for the group -‘:work:lab:conf:’, then searching for ‘work’ also searches for -‘{\(?:work\|lab\|conf\)}’ and searching for ‘-work’ searches for all -headlines but those with one of the tags in the group (i.e., -‘-{\(?:work\|lab\|conf\)}’). - - You may also test for properties (see *note Properties and Columns::) -at the same time as matching tags. The properties may be real -properties, or special properties that represent other metadata (see -*note Special Properties::). For example, the property ‘TODO’ -represents the TODO keyword of the entry. Or, the property ‘LEVEL’ -represents the level of an entry. So searching -‘+LEVEL=3+boss-TODO="DONE"’ lists all level three headlines that have -the tag ‘boss’ and are _not_ marked with the TODO keyword ‘DONE’. In -buffers with ‘org-odd-levels-only’ set, ‘LEVEL’ does not count the -number of stars, but ‘LEVEL=2’ corresponds to 3 stars etc. - - Here are more examples: - -‘work+TODO="WAITING"’ - Select ‘work’-tagged TODO lines with the specific TODO keyword - ‘WAITING’. - -‘work+TODO="WAITING"|home+TODO="WAITING"’ - Waiting tasks both at work and at home. - - When matching properties, a number of different operators can be used -to test the value of a property. Here is a complex example: - - +work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<2 - +With={Sarah\|Denny}+SCHEDULED>="<2008-10-11>" - -The type of comparison depends on how the comparison value is written: - - • If the comparison value is a plain number, a numerical comparison - is done, and the allowed operators are ‘<’, ‘=’, ‘>’, ‘<=’, ‘>=’, - and ‘<>’. - - • If the comparison value is enclosed in double-quotes, a string - comparison is done, and the same operators are allowed. - - • If the comparison value is enclosed in double-quotes _and_ angular - brackets (like ‘DEADLINE<="<2008-12-24 18:30>"’), both values are - assumed to be date/time specifications in the standard Org way, and - the comparison is done accordingly. Valid values also include - ‘"<now>"’ for now (including time), ‘"<today>"’, and ‘"<tomorrow>"’ - for these days at 0:00 hours, i.e., without a time specification. - You can also use strings like ‘"<+5d>"’ or ‘"<-2m>"’ with units - ‘d’, ‘w’, ‘m’, and ‘y’ for day, week, month, and year, - respectively. - - • If the comparison value is enclosed in curly braces, a regexp match - is performed, with ‘=’ meaning that the regexp matches the property - value, and ‘<>’ meaning that it does not match. - - So the search string in the example finds entries tagged ‘work’ but -not ‘boss’, which also have a priority value ‘A’, a ‘Coffee’ property -with the value ‘unlimited’, an ‘EFFORT’ property that is numerically -smaller than 2, a ‘With’ property that is matched by the regular -expression ‘Sarah\|Denny’, and that are scheduled on or after October -11, 2008. - - You can configure Org mode to use property inheritance during a -search, but beware that this can slow down searches considerably. See -*note Property Inheritance::, for details. - - For backward compatibility, and also for typing speed, there is also -a different way to test TODO states in a search. For this, terminate -the tags/property part of the search string (which may include several -terms connected with ‘|’) with a ‘/’ and then specify a Boolean -expression just for TODO keywords. The syntax is then similar to that -for tags, but should be applied with care: for example, a positive -selection on several TODO keywords cannot meaningfully be combined with -boolean AND. However, _negative selection_ combined with AND can be -meaningful. To make sure that only lines are checked that actually have -any TODO keyword (resulting in a speed-up), use ‘M-x org-agenda M’, or -equivalently start the TODO part after the slash with ‘!’. Using ‘M-x -org-agenda M’ or ‘/!’ does not match TODO keywords in a DONE state. -Examples: - -‘work/WAITING’ - Same as ‘work+TODO="WAITING"’. - -‘work/!-WAITING-NEXT’ - Select ‘work’-tagged TODO lines that are neither ‘WAITING’ nor - ‘NEXT’. - -‘work/!+WAITING|+NEXT’ - Select ‘work’-tagged TODO lines that are either ‘WAITING’ or - ‘NEXT’. - - -File: org.info, Node: Search view, Next: Stuck projects, Prev: Matching tags and properties, Up: Built-in Agenda Views - -11.3.4 Search view ------------------- - -This agenda view is a general text search facility for Org mode entries. -It is particularly useful to find notes. - -‘M-x org-agenda s’ (‘org-search-view’) - This is a special search that lets you select entries by matching a - substring or specific words using a boolean logic. - - For example, the search string ‘computer equipment’ matches entries -that contain ‘computer equipment’ as a substring, even if the two words -are separated by more space or a line break. - - Search view can also search for specific keywords in the entry, using -Boolean logic. The search string ‘+computer +wifi -ethernet --{8\.11[bg]}’ matches note entries that contain the keywords ‘computer’ -and ‘wifi’, but not the keyword ‘ethernet’, and which are also not -matched by the regular expression ‘8\.11[bg]’, meaning to exclude both -‘8.11b’ and ‘8.11g’. The first ‘+’ is necessary to turn on boolean -search, other ‘+’ characters are optional. For more details, see the -docstring of the command ‘org-search-view’. - - You can incrementally and conveniently adjust a boolean search from -the agenda search view with the following keys - -‘[’ Add a positive search word -‘]’ Add a negative search word -‘{’ Add a positive regular expression -‘}’ Add a negative regular expression - - Note that in addition to the agenda files, this command also searches -the files listed in ‘org-agenda-text-search-extra-files’. - - -File: org.info, Node: Stuck projects, Prev: Search view, Up: Built-in Agenda Views - -11.3.5 Stuck projects ---------------------- - -If you are following a system like David Allen’s GTD to organize your -work, one of the “duties” you have is a regular review to make sure that -all projects move along. A _stuck_ project is a project that has no -defined next actions, so it never shows up in the TODO lists Org mode -produces. During the review, you need to identify such projects and -define next actions for them. - -‘M-x org-agenda #’ (‘org-agenda-list-stuck-projects’) - List projects that are stuck. - -‘M-x org-agenda !’ - Customize the variable ‘org-stuck-projects’ to define what a stuck - project is and how to find it. - - You almost certainly need to configure this view before it works for -you. The built-in default assumes that all your projects are level-2 -headlines, and that a project is not stuck if it has at least one entry -marked with a TODO keyword ‘TODO’ or ‘NEXT’ or ‘NEXTACTION’. - - Let’s assume that you, in your own way of using Org mode, identify -projects with a tag ‘:PROJECT:’, and that you use a TODO keyword ‘MAYBE’ -to indicate a project that should not be considered yet. Let’s further -assume that the TODO keyword ‘DONE’ marks finished projects, and that -‘NEXT’ and ‘TODO’ indicate next actions. The tag ‘:@shop:’ indicates -shopping and is a next action even without the NEXT tag. Finally, if -the project contains the special word ‘IGNORE’ anywhere, it should not -be listed either. In this case you would start by identifying eligible -projects with a tags/TODO match (see *note Tag Searches::) -‘+PROJECT/-MAYBE-DONE’, and then check for ‘TODO’, ‘NEXT’, ‘@shop’, and -‘IGNORE’ in the subtree to identify projects that are not stuck. The -correct customization for this is: - - (setq org-stuck-projects - '("+PROJECT/-MAYBE-DONE" ("NEXT" "TODO") ("@shop") - "\\<IGNORE\\>")) - - Note that if a project is identified as non-stuck, the subtree of -this entry is searched for stuck projects. - - -File: org.info, Node: Presentation and Sorting, Next: Agenda Commands, Prev: Built-in Agenda Views, Up: Agenda Views - -11.4 Presentation and Sorting -============================= - -Before displaying items in an agenda view, Org mode visually prepares -the items and sorts them. Each item occupies a single line. The line -starts with a _prefix_ that contains the _category_ (see *note -Categories::) of the item and other important information. You can -customize in which column tags are displayed through -‘org-agenda-tags-column’. You can also customize the prefix using the -option ‘org-agenda-prefix-format’. This prefix is followed by a -cleaned-up version of the outline headline associated with the item. - -* Menu: - -* Categories:: Not all tasks are equal. -* Time-of-day specifications:: How the agenda knows the time. -* Sorting of agenda items:: The order of things. -* Filtering/limiting agenda items:: Dynamically narrow the agenda. - - -File: org.info, Node: Categories, Next: Time-of-day specifications, Up: Presentation and Sorting - -11.4.1 Categories ------------------ - -The category is a broad label assigned to each agenda item. By default, -the category is simply derived from the file name, but you can also -specify it with a special line in the buffer, like this: - - #+CATEGORY: Thesis - - If you would like to have a special category for a single entry or a -(sub)tree, give the entry a ‘CATEGORY’ property with the special -category you want to apply as the value. - - The display in the agenda buffer looks best if the category is not -longer than 10 characters. You can set up icons for category by -customizing the ‘org-agenda-category-icon-alist’ variable. - - -File: org.info, Node: Time-of-day specifications, Next: Sorting of agenda items, Prev: Categories, Up: Presentation and Sorting - -11.4.2 Time-of-day specifications ---------------------------------- - -Org mode checks each agenda item for a time-of-day specification. The -time can be part of the timestamp that triggered inclusion into the -agenda, for example - - <2005-05-10 Tue 19:00> - -Time ranges can be specified with two timestamps: - - <2005-05-10 Tue 20:30>--<2005-05-10 Tue 22:15> - - In the headline of the entry itself, a time(range)—like ‘12:45’ or a -‘8:30-1pm’—may also appear as plain text(1). - - If the agenda integrates the Emacs diary (see *note Weekly/daily -agenda::), time specifications in diary entries are recognized as well. - - For agenda display, Org mode extracts the time and displays it in a -standard 24 hour format as part of the prefix. The example times in the -previous paragraphs would end up in the agenda like this: - - 8:30-13:00 Arthur Dent lies in front of the bulldozer - 12:45...... Ford Prefect arrives and takes Arthur to the pub - 19:00...... The Vogon reads his poem - 20:30-22:15 Marvin escorts the Hitchhikers to the bridge - - If the agenda is in single-day mode, or for the display of today, the -timed entries are embedded in a time grid, like - - 8:00...... ------------------ - 8:30-13:00 Arthur Dent lies in front of the bulldozer - 10:00...... ------------------ - 12:00...... ------------------ - 12:45...... Ford Prefect arrives and takes Arthur to the pub - 14:00...... ------------------ - 16:00...... ------------------ - 18:00...... ------------------ - 19:00...... The Vogon reads his poem - 20:00...... ------------------ - 20:30-22:15 Marvin escorts the Hitchhikers to the bridge - - The time grid can be turned on and off with the variable -‘org-agenda-use-time-grid’, and can be configured with -‘org-agenda-time-grid’. - - ---------- Footnotes ---------- - - (1) You can, however, disable this by setting -‘org-agenda-search-headline-for-time’ variable to a ‘nil’ value. - - -File: org.info, Node: Sorting of agenda items, Next: Filtering/limiting agenda items, Prev: Time-of-day specifications, Up: Presentation and Sorting - -11.4.3 Sorting of agenda items ------------------------------- - -Before being inserted into a view, the items are sorted. How this is -done depends on the type of view. - - • For the daily/weekly agenda, the items for each day are sorted. - The default order is to first collect all items containing an - explicit time-of-day specification. These entries are shown at the - beginning of the list, as a _schedule_ for the day. After that, - items remain grouped in categories, in the sequence given by - ‘org-agenda-files’. Within each category, items are sorted by - priority (see *note Priorities::), which is composed of the base - priority (2000 for priority ‘A’, 1000 for ‘B’, and 0 for ‘C’), plus - additional increments for overdue scheduled or deadline items. - - • For the TODO list, items remain in the order of categories, but - within each category, sorting takes place according to priority - (see *note Priorities::). The priority used for sorting derives - from the priority cookie, with additions depending on how close an - item is to its due or scheduled date. - - • For tags matches, items are not sorted at all, but just appear in - the sequence in which they are found in the agenda files. - - Sorting can be customized using the variable -‘org-agenda-sorting-strategy’, and may also include criteria based on -the estimated effort of an entry (see *note Effort Estimates::). - - -File: org.info, Node: Filtering/limiting agenda items, Prev: Sorting of agenda items, Up: Presentation and Sorting - -11.4.4 Filtering/limiting agenda items --------------------------------------- - -Agenda built-in or custom commands are statically defined. Agenda -filters and limits allow to flexibly narrow down the list of agenda -entries. - - _Filters_ only change the visibility of items, are very fast and are -mostly used interactively(1). You can switch quickly between different -filters without having to recreate the agenda. _Limits_ on the other -hand take effect before the agenda buffer is populated, so they are -mostly useful when defined as local variables within custom agenda -commands. - -Filtering in the agenda -....................... - -The general filtering command is ‘org-agenda-filter’, bound to ‘/’. -Before we introduce it, we describe commands for individual filter -types. All filtering commands handle prefix arguments in the same way: -A single ‘C-u’ prefix negates the filter, so it removes lines selected -by the filter. A double prefix adds the new filter condition to the -one(s) already in place, so filter elements are accumulated. - -‘\’ (‘org-agenda-filter-by-tag’) - Filter the agenda view with respect to a tag. You are prompted for - a tag selection letter; ‘<SPC>’ means any tag at all. Pressing - ‘<TAB>’ at that prompt offers completion to select a tag, including - any tags that do not have a selection character. The command then - hides all entries that do not contain or inherit this tag. - Pressing ‘+’ or ‘-’ at the prompt switches between filtering for - and against the next tag. To clear the filter, press ‘\’ twice - (once to call the command again, and once at the prompt). - -‘<’ (‘org-agenda-filter-by-category’) - Filter by category of the line at point, and show only entries with - this category. When called with a prefix argument, hide all - entries with the category at point. To clear the filter, call this - command again by pressing ‘<’. - -‘=’ (‘org-agenda-filter-by-regexp’) - Filter the agenda view by a regular expression: only show agenda - entries matching the regular expression the user entered. To clear - the filter, call the command again by pressing ‘=’. - -‘_’ (‘org-agenda-filter-by-effort’) - Filter the agenda view with respect to effort estimates, so select - tasks that take the right amount of time. You first need to set up - a list of efforts globally, for example - - (setq org-global-properties - '(("Effort_ALL". "0 0:10 0:30 1:00 2:00 3:00 4:00"))) - - You can then filter for an effort by first typing an operator, one - of ‘<’, ‘>’ and ‘=’, and then the one-digit index of an effort - estimate in your array of allowed values, where ‘0’ means the 10th - value. The filter then restricts to entries with effort - smaller-or-equal, equal, or larger-or-equal than the selected - value. For application of the operator, entries without a defined - effort are treated according to the value of - ‘org-sort-agenda-noeffort-is-high’. To clear the filter, press ‘_’ - twice (once to call the command again, and once at the first - prompt). - -‘^’ (‘org-agenda-filter-by-top-headline’) - Filter the current agenda view and only display items that fall - under the same top-level headline as the current entry. To clear - the filter, call this command again by pressing ‘^’. - -‘/’ (‘org-agenda-filter’) - This is the unified interface to four of the five filter methods - described above. At the prompt, specify different filter elements - in a single string, with full completion support. For example, - - +work-John+<0:10-/plot/ - - selects entries with category ‘work’ and effort estimates below 10 - minutes, and deselects entries with tag ‘John’ or matching the - regexp ‘plot’ (see *note Regular Expressions::). You can leave ‘+’ - out if that does not lead to ambiguities. The sequence of elements - is arbitrary. The filter syntax assumes that there is no overlap - between categories and tags. Otherwise, tags take priority. If - you reply to the prompt with the empty string, all filtering is - removed. If a filter is specified, it replaces all current - filters. But if you call the command with a double prefix - argument, or if you add an additional ‘+’ (e.g., ‘++work’) to the - front of the string, the new filter elements are added to the - active ones. A single prefix argument applies the entire filter in - a negative sense. - -‘|’ (‘org-agenda-filter-remove-all’) - Remove all filters in the current agenda view. - -Computed tag filtering -...................... - -If the variable ‘org-agenda-auto-exclude-function’ is set to a -user-defined function, that function can select tags that should be used -as a tag filter when requested. The function will be called with -lower-case versions of all tags represented in the current view. The -function should return ‘"-tag"’ if the filter should remove entries with -that tag, ‘"+tag"’ if only entries with this tag should be kept, or -‘nil’ if that tag is irrelevant. For example, let’s say you use a ‘Net’ -tag to identify tasks which need network access, an ‘Errand’ tag for -errands in town, and a ‘Call’ tag for making phone calls. You could -auto-exclude these tags based on the availability of the Internet, and -outside of business hours, with something like this: - - (defun my-auto-exclude-fn (tag) - (when (cond ((string= tag "net") - (/= 0 (call-process "/sbin/ping" nil nil nil - "-c1" "-q" "-t1" "mail.gnu.org"))) - ((member tag '("errand" "call")) - (let ((hr (nth 2 (decode-time)))) - (or (< hr 8) (> hr 21))))) - (concat "-" tag))) - - (setq org-agenda-auto-exclude-function #'my-auto-exclude-fn) - - You can apply this self-adapting filter by using a triple prefix -argument to ‘org-agenda-filter’, i.e. press ‘C-u C-u C-u /’, or by -pressing ‘<RET>’ in ‘org-agenda-filter-by-tag’. - -Setting limits for the agenda -............................. - -Here is a list of options that you can set, either globally, or locally -in your custom agenda views (see *note Custom Agenda Views::). - -‘org-agenda-max-entries’ - Limit the number of entries. - -‘org-agenda-max-effort’ - Limit the duration of accumulated efforts (as minutes). - -‘org-agenda-max-todos’ - Limit the number of entries with TODO keywords. - -‘org-agenda-max-tags’ - Limit the number of tagged entries. - - When set to a positive integer, each option excludes entries from -other categories: for example, ‘(setq org-agenda-max-effort 100)’ limits -the agenda to 100 minutes of effort and exclude any entry that has no -effort property. If you want to include entries with no effort -property, use a negative value for ‘org-agenda-max-effort’. One useful -setup is to use ‘org-agenda-max-entries’ locally in a custom command. -For example, this custom command displays the next five entries with a -‘NEXT’ TODO keyword. - - (setq org-agenda-custom-commands - '(("n" todo "NEXT" - ((org-agenda-max-entries 5))))) - - Once you mark one of these five entry as DONE, rebuilding the agenda -will again the next five entries again, including the first entry that -was excluded so far. - - You can also dynamically set temporary limits, which are lost when -rebuilding the agenda: - -‘~’ (‘org-agenda-limit-interactively’) - This prompts for the type of limit to apply and its value. - - ---------- Footnotes ---------- - - (1) Custom agenda commands can preset a filter by binding one of the -variables ‘org-agenda-tag-filter-preset’, -‘org-agenda-category-filter-preset’, ‘org-agenda-effort-filter-preset’ -or ‘org-agenda-regexp-filter-preset’ as an option. This filter is then -applied to the view and persists as a basic filter through refreshes and -more secondary filtering. The filter is a global property of the entire -agenda view—in a block agenda, you should only set this in the global -options section, not in the section of an individual block. - - -File: org.info, Node: Agenda Commands, Next: Custom Agenda Views, Prev: Presentation and Sorting, Up: Agenda Views - -11.5 Commands in the Agenda Buffer -================================== - -Entries in the agenda buffer are linked back to the Org file or diary -file where they originate. You are not allowed to edit the agenda -buffer itself, but commands are provided to show and jump to the -original entry location, and to edit the Org files “remotely” from the -agenda buffer. In this way, all information is stored only once, -removing the risk that your agenda and note files may diverge. - - Some commands can be executed with mouse clicks on agenda lines. For -the other commands, point needs to be in the desired line. - -Motion ------- - -‘n’ (‘org-agenda-next-line’) - Next line (same as ‘<DOWN>’ and ‘C-n’). - -‘p’ (‘org-agenda-previous-line’) - Previous line (same as ‘<UP>’ and ‘C-p’). - -View/Go to Org file -------------------- - -‘<SPC>’ or ‘mouse-3’ (‘org-agenda-show-and-scroll-up’) - Display the original location of the item in another window. With - a prefix argument, make sure that drawers stay folded. - -‘L’ (‘org-agenda-recenter’) - Display original location and recenter that window. - -‘<TAB>’ or ‘mouse-2’ (‘org-agenda-goto’) - Go to the original location of the item in another window. - -‘<RET>’ (‘org-agenda-switch-to’) - Go to the original location of the item and delete other windows. - -‘F’ (‘org-agenda-follow-mode’) - Toggle Follow mode. In Follow mode, as you move point through the - agenda buffer, the other window always shows the corresponding - location in the Org file. The initial setting for this mode in new - agenda buffers can be set with the variable - ‘org-agenda-start-with-follow-mode’. - -‘C-c C-x b’ (‘org-agenda-tree-to-indirect-buffer’) - Display the entire subtree of the current item in an indirect - buffer. With a numeric prefix argument N, go up to level N and - then take that tree. If N is negative, go up that many levels. - With a ‘C-u’ prefix, do not remove the previously used indirect - buffer. - -‘C-c C-o’ (‘org-agenda-open-link’) - Follow a link in the entry. This offers a selection of any links - in the text belonging to the referenced Org node. If there is only - one link, follow it without a selection prompt. - -Change display --------------- - -‘A’ - Interactively select another agenda view and append it to the - current view. - -‘o’ - Delete other windows. - -‘v d’ or short ‘d’ (‘org-agenda-day-view’) - Switch to day view. When switching to day view, this setting - becomes the default for subsequent agenda refreshes. A numeric - prefix argument may be used to jump directly to a specific day of - the year. For example, ‘32 d’ jumps to February 1st. When setting - day view, a year may be encoded in the prefix argument as well. - For example, ‘200712 d’ jumps to January 12, 2007. If such a year - specification has only one or two digits, it is expanded into one - of the 30 next years or the last 69 years. - -‘v w’ or short ‘w’ (‘org-agenda-week-view’) - Switch to week view. When switching week view, this setting - becomes the default for subsequent agenda refreshes. A numeric - prefix argument may be used to jump directly to a specific day of - the ISO week. For example ‘9 w’ to ISO week number 9. When - setting week view, a year may be encoded in the prefix argument as - well. For example, ‘200712 w’ jumps to week 12 in 2007. If such a - year specification has only one or two digits, it is expanded into - one of the 30 next years or the last 69 years. - -‘v m’ (‘org-agenda-month-view’) - Switch to month view. Because month views are slow to create, they - do not become the default for subsequent agenda refreshes. A - numeric prefix argument may be used to jump directly to a specific - day of the month. When setting month view, a year may be encoded - in the prefix argument as well. For example, ‘200712 m’ jumps to - December, 2007. If such a year specification has only one or two - digits, it is expanded into one of the 30 next years or the last 69 - years. - -‘v y’ (‘org-agenda-year-view’) - Switch to year view. Because year views are slow to create, they - do not become the default for subsequent agenda refreshes. A - numeric prefix argument may be used to jump directly to a specific - day of the year. - -‘v <SPC>’ (‘org-agenda-reset-view’) - Reset the current view to ‘org-agenda-span’. - -‘f’ (‘org-agenda-later’) - Go forward in time to display the span following the current one. - For example, if the display covers a week, switch to the following - week. With a prefix argument, repeat that many times. - -‘b’ (‘org-agenda-earlier’) - Go backward in time to display earlier dates. - -‘.’ (‘org-agenda-goto-today’) - Go to today. - -‘j’ (‘org-agenda-goto-date’) - Prompt for a date and go there. - -‘J’ (‘org-agenda-clock-goto’) - Go to the currently clocked-in task _in the agenda buffer_. - -‘D’ (‘org-agenda-toggle-diary’) - Toggle the inclusion of diary entries. See *note Weekly/daily - agenda::. - -‘v l’ or ‘v L’ or short ‘l’ (‘org-agenda-log-mode’) - Toggle Logbook mode. In Logbook mode, entries that were marked as - done while logging was on (see the variable ‘org-log-done’) are - shown in the agenda, as are entries that have been clocked on that - day. You can configure the entry types that should be included in - log mode using the variable ‘org-agenda-log-mode-items’. When - called with a ‘C-u’ prefix argument, show all possible logbook - entries, including state changes. When called with two prefix - arguments ‘C-u C-u’, show only logging information, nothing else. - ‘v L’ is equivalent to ‘C-u v l’. - -‘v [’ or short ‘[’ (‘org-agenda-manipulate-query-add’) - Include inactive timestamps into the current view. Only for - weekly/daily agenda. - -‘v a’ (‘org-agenda-archives-mode’) - Toggle Archives mode. In Archives mode, trees that are archived - (see *note Internal archiving::) are also scanned when producing - the agenda. To exit archives mode, press ‘v a’ again. - -‘v A’ - Toggle Archives mode. Include all archive files as well. - -‘v R’ or short ‘R’ (‘org-agenda-clockreport-mode’) - Toggle Clockreport mode. In Clockreport mode, the daily/weekly - agenda always shows a table with the clocked times for the time - span and file scope covered by the current agenda view. The - initial setting for this mode in new agenda buffers can be set with - the variable ‘org-agenda-start-with-clockreport-mode’. By using a - prefix argument when toggling this mode (i.e., ‘C-u R’), the clock - table does not show contributions from entries that are hidden by - agenda filtering(1). See also the variable - ‘org-clock-report-include-clocking-task’. - -‘v c’ - Show overlapping clock entries, clocking gaps, and other clocking - problems in the current agenda range. You can then visit clocking - lines and fix them manually. See the variable - ‘org-agenda-clock-consistency-checks’ for information on how to - customize the definition of what constituted a clocking problem. - To return to normal agenda display, press ‘l’ to exit Logbook mode. - -‘v E’ or short ‘E’ (‘org-agenda-entry-text-mode’) - Toggle entry text mode. In entry text mode, a number of lines from - the Org outline node referenced by an agenda line are displayed - below the line. The maximum number of lines is given by the - variable ‘org-agenda-entry-text-maxlines’. Calling this command - with a numeric prefix argument temporarily modifies that number to - the prefix value. - -‘G’ (‘org-agenda-toggle-time-grid’) - Toggle the time grid on and off. See also the variables - ‘org-agenda-use-time-grid’ and ‘org-agenda-time-grid’. - -‘r’ (‘org-agenda-redo’) -‘g’ - Recreate the agenda buffer, for example to reflect the changes - after modification of the timestamps of items with ‘S-<LEFT>’ and - ‘S-<RIGHT>’. When the buffer is the global TODO list, a prefix - argument is interpreted to create a selective list for a specific - TODO keyword. - -‘C-x C-s’ or short ‘s’ (‘org-save-all-org-buffers’) - Save all Org buffers in the current Emacs session, and also the - locations of IDs. - -‘C-c C-x C-c’ (‘org-agenda-columns’) - Invoke column view (see *note Column View::) in the agenda buffer. - The column view format is taken from the entry at point, or, if - there is no entry at point, from the first entry in the agenda - view. So whatever the format for that entry would be in the - original buffer (taken from a property, from a ‘COLUMNS’ keyword, - or from the default variable ‘org-columns-default-format’) is used - in the agenda. - -‘C-c C-x >’ (‘org-agenda-remove-restriction-lock’) - Remove the restriction lock on the agenda, if it is currently - restricted to a file or subtree (see *note Agenda Files::). - -‘M-<UP>’ (‘org-agenda-drag-line-backward’) - Drag the line at point backward one line. With a numeric prefix - argument, drag backward by that many lines. - - Moving agenda lines does not persist after an agenda refresh and - does not modify the contributing Org files. - -‘M-<DOWN>’ (‘org-agenda-drag-line-forward’) - Drag the line at point forward one line. With a numeric prefix - argument, drag forward by that many lines. - -Remote editing --------------- - -‘0--9’ - Digit argument. - -‘C-_’ (‘org-agenda-undo’) - Undo a change due to a remote editing command. The change is - undone both in the agenda buffer and in the remote buffer. - -‘t’ (‘org-agenda-todo’) - Change the TODO state of the item, both in the agenda and in the - original Org file. A prefix arg is passed through to the - ‘org-todo’ command, so for example a ‘C-u’ prefix are will trigger - taking a note to document the state change. - -‘C-S-<RIGHT>’ (‘org-agenda-todo-nextset’) - Switch to the next set of TODO keywords. - -‘C-S-<LEFT>’, ‘org-agenda-todo-previousset’ - Switch to the previous set of TODO keywords. - -‘C-k’ (‘org-agenda-kill’) - Delete the current agenda item along with the entire subtree - belonging to it in the original Org file. If the text to be - deleted remotely is longer than one line, the kill needs to be - confirmed by the user. See variable ‘org-agenda-confirm-kill’. - -‘C-c C-w’ (‘org-agenda-refile’) - Refile the entry at point. - -‘C-c C-x C-a’ or short ‘a’ (‘org-agenda-archive-default-with-confirmation’) - Archive the subtree corresponding to the entry at point using the - default archiving command set in ‘org-archive-default-command’. - When using the ‘a’ key, confirmation is required. - -‘C-c C-x a’ (‘org-agenda-toggle-archive-tag’) - Toggle the archive tag (see *note Internal archiving::) for the - current headline. - -‘C-c C-x A’ (‘org-agenda-archive-to-archive-sibling’) - Move the subtree corresponding to the current entry to its _archive - sibling_. - -‘C-c C-x C-s’ or short ‘$’ (‘org-agenda-archive’) - Archive the subtree corresponding to the current headline. This - means the entry is moved to the configured archive location, most - likely a different file. - -‘T’ (‘org-agenda-show-tags’) - Show all tags associated with the current item. This is useful if - you have turned off ‘org-agenda-show-inherited-tags’, but still - want to see all tags of a headline occasionally. - -‘:’ (‘org-agenda-set-tags’) - Set tags for the current headline. If there is an active region in - the agenda, change a tag for all headings in the region. - -‘,’ (‘org-agenda-priority’) - Set the priority for the current item. Org mode prompts for the - priority character. If you reply with ‘<SPC>’, the priority cookie - is removed from the entry. - -‘+’ or ‘S-<UP>’ (‘org-agenda-priority-up’) - Increase the priority of the current item. The priority is changed - in the original buffer, but the agenda is not resorted. Use the - ‘r’ key for this. - -‘-’ or ‘S-<DOWN>’ (‘org-agenda-priority-down’) - Decrease the priority of the current item. - -‘C-c C-x e’ or short ‘e’ (‘org-agenda-set-effort’) - Set the effort property for the current item. - -‘C-c C-z’ or short ‘z’ (‘org-agenda-add-note’) - Add a note to the entry. This note is recorded, and then filed to - the same location where state change notes are put. Depending on - ‘org-log-into-drawer’, this may be inside a drawer. - -‘C-c C-a’ (‘org-attach’) - Dispatcher for all command related to attachments. - -‘C-c C-s’ (‘org-agenda-schedule’) - Schedule this item. With a prefix argument, remove the scheduling - timestamp - -‘C-c C-d’ (‘org-agenda-deadline’) - Set a deadline for this item. With a prefix argument, remove the - deadline. - -‘S-<RIGHT>’ (‘org-agenda-do-date-later’) - Change the timestamp associated with the current line by one day - into the future. If the date is in the past, the first call to - this command moves it to today. With a numeric prefix argument, - change it by that many days. For example, ‘3 6 5 S-<RIGHT>’ - changes it by a year. With a ‘C-u’ prefix, change the time by one - hour. If you immediately repeat the command, it will continue to - change hours even without the prefix argument. With a double ‘C-u - C-u’ prefix, do the same for changing minutes. The stamp is - changed in the original Org file, but the change is not directly - reflected in the agenda buffer. Use ‘r’ or ‘g’ to update the - buffer. - -‘S-<LEFT>’ (‘org-agenda-do-date-earlier’) - Change the timestamp associated with the current line by one day - into the past. - -‘>’ (‘org-agenda-date-prompt’) - Change the timestamp associated with the current line. The key ‘>’ - has been chosen, because it is the same as ‘S-.’ on my keyboard. - -‘I’ (‘org-agenda-clock-in’) - Start the clock on the current item. If a clock is running - already, it is stopped first. - -‘O’ (‘org-agenda-clock-out’) - Stop the previously started clock. - -‘X’ (‘org-agenda-clock-cancel’) - Cancel the currently running clock. - -‘J’ (‘org-agenda-clock-goto’) - Jump to the running clock in another window. - -‘k’ (‘org-agenda-capture’) - Like ‘org-capture’, but use the date at point as the default date - for the capture template. See ‘org-capture-use-agenda-date’ to - make this the default behavior of ‘org-capture’. - -Bulk remote editing selected entries ------------------------------------- - -‘m’ (‘org-agenda-bulk-mark’) - - Mark the entry at point for bulk action. If there is an active - region in the agenda, mark the entries in the region. With numeric - prefix argument, mark that many successive entries. - -‘*’ (‘org-agenda-bulk-mark-all’) - - Mark all visible agenda entries for bulk action. - -‘u’ (‘org-agenda-bulk-unmark’) - - Unmark entry for bulk action. - -‘U’ (‘org-agenda-bulk-remove-all-marks’) - - Unmark all marked entries for bulk action. - -‘M-m’ (‘org-agenda-bulk-toggle’) - - Toggle mark of the entry at point for bulk action. - -‘M-*’ (‘org-agenda-bulk-toggle-all’) - - Toggle mark of every entry for bulk action. - -‘%’ (‘org-agenda-bulk-mark-regexp’) - - Mark entries matching a regular expression for bulk action. - -‘B’ (‘org-agenda-bulk-action’) - - Bulk action: act on all marked entries in the agenda. This prompts - for another key to select the action to be applied. The prefix - argument to ‘B’ is passed through to the ‘s’ and ‘d’ commands, to - bulk-remove these special timestamps. By default, marks are - removed after the bulk. If you want them to persist, set - ‘org-agenda-bulk-persistent-marks’ to ‘t’ or hit ‘p’ at the prompt. - - ‘p’ - Toggle persistent marks. - - ‘$’ - Archive all selected entries. - - ‘A’ - Archive entries by moving them to their respective archive - siblings. - - ‘t’ - Change TODO state. This prompts for a single TODO keyword and - changes the state of all selected entries, bypassing blocking - and suppressing logging notes—but not timestamps. - - ‘+’ - Add a tag to all selected entries. - - ‘-’ - Remove a tag from all selected entries. - - ‘s’ - Schedule all items to a new date. To shift existing schedule - dates by a fixed number of days, use something starting with - double plus at the prompt, for example ‘++8d’ or ‘++2w’. - - ‘d’ - Set deadline to a specific date. - - ‘r’ - Prompt for a single refile target and move all entries. The - entries are no longer in the agenda; refresh (‘g’) to bring - them back. - - ‘S’ - Reschedule randomly into the coming N days. N is prompted - for. With a prefix argument (‘C-u B S’), scatter only across - weekdays. - - ‘f’ - Apply a function(2) to marked entries. For example, the - function below sets the ‘CATEGORY’ property of the entries to - ‘web’. - - (defun set-category () - (interactive "P") - (let ((marker (or (org-get-at-bol 'org-hd-marker) - (org-agenda-error)))) - (org-with-point-at marker - (org-back-to-heading t) - (org-set-property "CATEGORY" "web")))) - -Calendar commands ------------------ - -‘c’ (‘org-agenda-goto-calendar’) - Open the Emacs calendar and go to the date at point in the agenda. - -‘c’ (‘org-calendar-goto-agenda’) - When in the calendar, compute and show the Org agenda for the date - at point. - -‘i’ (‘org-agenda-diary-entry’) - - Insert a new entry into the diary, using the date at point and (for - block entries) the date at the mark. This adds to the Emacs diary - file(3), in a way similar to the ‘i’ command in the calendar. The - diary file pops up in another window, where you can add the entry. - - If you configure ‘org-agenda-diary-file’ to point to an Org file, - Org creates entries in that file instead. Most entries are stored - in a date-based outline tree that will later make it easy to - archive appointments from previous months/years. The tree is built - under an entry with a ‘DATE_TREE’ property, or else with years as - top-level entries. Emacs prompts you for the entry text—if you - specify it, the entry is created in ‘org-agenda-diary-file’ without - further interaction. If you directly press ‘<RET>’ at the prompt - without typing text, the target file is shown in another window for - you to finish the entry there. See also the ‘k r’ command. - -‘M’ (‘org-agenda-phases-of-moon’) - Show the phases of the moon for the three months around current - date. - -‘S’ (‘org-agenda-sunrise-sunset’) - Show sunrise and sunset times. The geographical location must be - set with calendar variables, see the documentation for the Emacs - calendar. - -‘C’ (‘org-agenda-convert-date’) - Convert the date at point into many other cultural and historic - calendars. - -‘H’ (‘org-agenda-holidays’) - Show holidays for three months around point date. - -Quit and exit -------------- - -‘q’ (‘org-agenda-quit’) - - Quit agenda, remove the agenda buffer. - -‘x’ (‘org-agenda-exit’) - - Exit agenda, remove the agenda buffer and all buffers loaded by - Emacs for the compilation of the agenda. Buffers created by the - user to visit Org files are not removed. - - ---------- Footnotes ---------- - - (1) Only tags filtering is respected here, effort filtering is -ignored. - - (2) You can also create persistent custom functions through -‘org-agenda-bulk-custom-functions’. - - (3) This file is parsed for the agenda when -‘org-agenda-include-diary’ is set. - - -File: org.info, Node: Custom Agenda Views, Next: Exporting Agenda Views, Prev: Agenda Commands, Up: Agenda Views - -11.6 Custom Agenda Views -======================== - -Custom agenda commands serve two purposes: to store and quickly access -frequently used TODO and tags searches, and to create special composite -agenda buffers. Custom agenda commands are accessible through the -dispatcher (see *note Agenda Dispatcher::), just like the default -commands. - -* Menu: - -* Storing searches:: Type once, use often. -* Block agenda:: All the stuff you need in a single buffer. -* Setting options:: Changing the rules. - - -File: org.info, Node: Storing searches, Next: Block agenda, Up: Custom Agenda Views - -11.6.1 Storing searches ------------------------ - -The first application of custom searches is the definition of keyboard -shortcuts for frequently used searches, either creating an agenda -buffer, or a sparse tree (the latter covering of course only the current -buffer). - - Custom commands are configured in the variable -‘org-agenda-custom-commands’. You can customize this variable, for -example by pressing ‘C’ from the agenda dispatcher (see *note Agenda -Dispatcher::). You can also directly set it with Emacs Lisp in the -Emacs init file. The following example contains all valid agenda views: - - (setq org-agenda-custom-commands - '(("x" agenda) - ("y" agenda*) - ("w" todo "WAITING") - ("W" todo-tree "WAITING") - ("u" tags "+boss-urgent") - ("v" tags-todo "+boss-urgent") - ("U" tags-tree "+boss-urgent") - ("f" occur-tree "\\<FIXME\\>") - ("h" . "HOME+Name tags searches") ;description for "h" prefix - ("hl" tags "+home+Lisa") - ("hp" tags "+home+Peter") - ("hk" tags "+home+Kim"))) - - The initial string in each entry defines the keys you have to press -after the dispatcher command in order to access the command. Usually -this is just a single character, but if you have many similar commands, -you can also define two-letter combinations where the first character is -the same in several combinations and serves as a prefix key(1). The -second parameter is the search type, followed by the string or regular -expression to be used for the matching. The example above will -therefore define: - -‘x’ - as a global search for agenda entries planned(2) this week/day. - -‘y’ - as the same search, but only for entries with an hour specification - like ‘[h]h:mm’—think of them as appointments. - -‘w’ - as a global search for TODO entries with ‘WAITING’ as the TODO - keyword. - -‘W’ - as the same search, but only in the current buffer and displaying - the results as a sparse tree. - -‘u’ - as a global tags search for headlines tagged ‘boss’ but not - ‘urgent’. - -‘v’ - The same search, but limiting it to headlines that are also TODO - items. - -‘U’ - as the same search, but only in the current buffer and displaying - the result as a sparse tree. - -‘f’ - to create a sparse tree (again, current buffer only) with all - entries containing the word ‘FIXME’. - -‘h’ - as a prefix command for a ‘HOME’ tags search where you have to - press an additional key (‘l’, ‘p’ or ‘k’) to select a name (Lisa, - Peter, or Kim) as additional tag to match. - - Note that ‘*-tree’ agenda views need to be called from an Org buffer -as they operate on the current buffer only. - - ---------- Footnotes ---------- - - (1) You can provide a description for a prefix key by inserting a -cons cell with the prefix and the description. - - (2) _Planned_ means here that these entries have some planning -information attached to them, like a time-stamp, a scheduled or a -deadline string. See ‘org-agenda-entry-types’ on how to set what -planning information is taken into account. - - -File: org.info, Node: Block agenda, Next: Setting options, Prev: Storing searches, Up: Custom Agenda Views - -11.6.2 Block agenda -------------------- - -Another possibility is the construction of agenda views that comprise -the results of _several_ commands, each of which creates a block in the -agenda buffer. The available commands include ‘agenda’ for the daily or -weekly agenda (as created with ‘a’) , ‘alltodo’ for the global TODO list -(as constructed with ‘t’), ‘stuck’ for the list of stuck projects (as -obtained with ‘#’) and the matching commands discussed above: ‘todo’, -‘tags’, and ‘tags-todo’. - - Here are two examples: - - (setq org-agenda-custom-commands - '(("h" "Agenda and Home-related tasks" - ((agenda "") - (tags-todo "home") - (tags "garden"))) - ("o" "Agenda and Office-related tasks" - ((agenda "") - (tags-todo "work") - (tags "office"))))) - -This defines ‘h’ to create a multi-block view for stuff you need to -attend to at home. The resulting agenda buffer contains your agenda for -the current week, all TODO items that carry the tag ‘home’, and also all -lines tagged with ‘garden’. Finally the command ‘o’ provides a similar -view for office tasks. - - -File: org.info, Node: Setting options, Prev: Block agenda, Up: Custom Agenda Views - -11.6.3 Setting options for custom commands ------------------------------------------- - -Org mode contains a number of variables regulating agenda construction -and display. The global variables define the behavior for all agenda -commands, including the custom commands. However, if you want to change -some settings just for a single custom view, you can do so. Setting -options requires inserting a list of variable names and values at the -right spot in ‘org-agenda-custom-commands’. For example: - - (setq org-agenda-custom-commands - '(("w" todo "WAITING" - ((org-agenda-sorting-strategy '(priority-down)) - (org-agenda-prefix-format " Mixed: "))) - ("U" tags-tree "+boss-urgent" - ((org-show-context-detail 'minimal))) - ("N" search "" - ((org-agenda-files '("~org/notes.org")) - (org-agenda-text-search-extra-files nil))))) - -Now the ‘w’ command sorts the collected entries only by priority, and -the prefix format is modified to just say ‘Mixed:’ instead of giving the -category of the entry. The sparse tags tree of ‘U’ now turns out -ultra-compact, because neither the headline hierarchy above the match, -nor the headline following the match are shown. The command ‘N’ does a -text search limited to only a single file. - - For command sets creating a block agenda, -‘org-agenda-custom-commands’ has two separate spots for setting options. -You can add options that should be valid for just a single command in -the set, and options that should be valid for all commands in the set. -The former are just added to the command entry; the latter must come -after the list of command entries. Going back to the block agenda -example (see *note Block agenda::), let’s change the sorting strategy -for the ‘h’ commands to ‘priority-down’, but let’s sort the results for -‘garden’ tags query in the opposite order, ‘priority-up’. This would -look like this: - - (setq org-agenda-custom-commands - '(("h" "Agenda and Home-related tasks" - ((agenda) - (tags-todo "home") - (tags "garden" - ((org-agenda-sorting-strategy '(priority-up))))) - ((org-agenda-sorting-strategy '(priority-down)))) - ("o" "Agenda and Office-related tasks" - ((agenda) - (tags-todo "work") - (tags "office"))))) - - As you see, the values and parentheses setting is a little complex. -When in doubt, use the customize interface to set this variable—it fully -supports its structure. Just one caveat: when setting options in this -interface, the _values_ are just Lisp expressions. So if the value is a -string, you need to add the double-quotes around the value yourself. - - To control whether an agenda command should be accessible from a -specific context, you can customize -‘org-agenda-custom-commands-contexts’. Let’s say for example that you -have an agenda command ‘o’ displaying a view that you only need when -reading emails. Then you would configure this option like this: - - (setq org-agenda-custom-commands-contexts - '(("o" (in-mode . "message-mode")))) - - You can also tell that the command key ‘o’ should refer to another -command key ‘r’. In that case, add this command key like this: - - (setq org-agenda-custom-commands-contexts - '(("o" "r" (in-mode . "message-mode")))) - - See the docstring of the variable for more information. - - -File: org.info, Node: Exporting Agenda Views, Next: Agenda Column View, Prev: Custom Agenda Views, Up: Agenda Views - -11.7 Exporting Agenda Views -=========================== - -If you are away from your computer, it can be very useful to have a -printed version of some agenda views to carry around. Org mode can -export custom agenda views as plain text, HTML(1), Postscript, PDF(2), -and iCalendar files. If you want to do this only occasionally, use the -following command: - -‘C-x C-w’ (‘org-agenda-write’) - - Write the agenda view to a file. - - If you need to export certain agenda views frequently, you can -associate any custom agenda command with a list of output file names(3). -Here is an example that first defines custom commands for the agenda and -the global TODO list, together with a number of files to which to export -them. Then we define two block agenda commands and specify file names -for them as well. File names can be relative to the current working -directory, or absolute. - - (setq org-agenda-custom-commands - '(("X" agenda "" nil ("agenda.html" "agenda.ps")) - ("Y" alltodo "" nil ("todo.html" "todo.txt" "todo.ps")) - ("h" "Agenda and Home-related tasks" - ((agenda "") - (tags-todo "home") - (tags "garden")) - nil - ("~/views/home.html")) - ("o" "Agenda and Office-related tasks" - ((agenda) - (tags-todo "work") - (tags "office")) - nil - ("~/views/office.ps" "~/calendars/office.ics")))) - - The extension of the file name determines the type of export. If it -is ‘.html’, Org mode uses the htmlize package to convert the buffer to -HTML and save it to this file name. If the extension is ‘.ps’, -‘ps-print-buffer-with-faces’ is used to produce Postscript output. If -the extension is ‘.ics’, iCalendar export is run export over all files -that were used to construct the agenda, and limit the export to entries -listed in the agenda. Any other extension produces a plain ASCII file. - - The export files are _not_ created when you use one of those commands -interactively because this might use too much overhead. Instead, there -is a special command to produce _all_ specified files in one step: - -‘e’ (‘org-store-agenda-views’) - Export all agenda views that have export file names associated with - them. - - You can use the options section of the custom agenda commands to also -set options for the export commands. For example: - - (setq org-agenda-custom-commands - '(("X" agenda "" - ((ps-number-of-columns 2) - (ps-landscape-mode t) - (org-agenda-prefix-format " [ ] ") - (org-agenda-with-colors nil) - (org-agenda-remove-tags t)) - ("theagenda.ps")))) - -This command sets two options for the Postscript exporter, to make it -print in two columns in landscape format—the resulting page can be cut -in two and then used in a paper agenda. The remaining settings modify -the agenda prefix to omit category and scheduling information, and -instead include a checkbox to check off items. We also remove the tags -to make the lines compact, and we do not want to use colors for the -black-and-white printer. Settings specified in -‘org-agenda-exporter-settings’ also apply, e.g., - - (setq org-agenda-exporter-settings - '((ps-number-of-columns 2) - (ps-landscape-mode t) - (org-agenda-add-entry-text-maxlines 5) - (htmlize-output-type 'css))) - -but the settings in ‘org-agenda-custom-commands’ take precedence. - - From the command line you may also use: - - emacs -eval (org-batch-store-agenda-views) -kill - -or, if you need to modify some parameters(4) - - emacs -eval '(org-batch-store-agenda-views \ - org-agenda-span (quote month) \ - org-agenda-start-day "2007-11-01" \ - org-agenda-include-diary nil \ - org-agenda-files (quote ("~/org/project.org")))' \ - -kill - -which creates the agenda views restricted to the file -‘~/org/project.org’, without diary entries and with a 30-day extent. - - You can also extract agenda information in a way that allows further -processing by other programs. See *note Extracting Agenda -Information::, for more information. - - ---------- Footnotes ---------- - - (1) For HTML you need to install Hrvoje Nikšić’s ‘htmlize.el’ as an -Emacs package from MELPA or from Hrvoje Nikšić’s repository -(https://github.com/hniksic/emacs-htmlize). - - (2) To create PDF output, the Ghostscript ps2pdf utility must be -installed on the system. Selecting a PDF file also creates the -postscript file. - - (3) If you want to store standard views like the weekly agenda or the -global TODO list as well, you need to define custom commands for them in -order to be able to specify file names. - - (4) Quoting depends on the system you use, please check the FAQ for -examples. - - -File: org.info, Node: Agenda Column View, Prev: Exporting Agenda Views, Up: Agenda Views - -11.8 Using Column View in the Agenda -==================================== - -Column view (see *note Column View::) is normally used to view and edit -properties embedded in the hierarchical structure of an Org file. It -can be quite useful to use column view also from the agenda, where -entries are collected by certain criteria. - -‘C-c C-x C-c’ (‘org-agenda-columns’) - - Turn on column view in the agenda. - - To understand how to use this properly, it is important to realize -that the entries in the agenda are no longer in their proper outline -environment. This causes the following issues: - - 1. Org needs to make a decision which columns format to use. Since - the entries in the agenda are collected from different files, and - different files may have different columns formats, this is a - non-trivial problem. Org first checks if - ‘org-overriding-columns-format’ is currently set, and if so, takes - the format from there. You should set this variable only in the - _local settings section_ of a custom agenda command (see *note - Custom Agenda Views::) to make it valid for that specific agenda - view. If no such binding exists, it checks, in sequence, - ‘org-columns-default-format-for-agenda’, the format associated with - the first item in the agenda (through a property or a ‘#+COLUMNS’ - setting in that buffer) and finally ‘org-columns-default-format’. - - 2. If any of the columns has a summary type defined (see *note Column - attributes::), turning on column view in the agenda visits all - relevant agenda files and make sure that the computations of this - property are up to date. This is also true for the special - ‘CLOCKSUM’ property. Org then sums the values displayed in the - agenda. In the daily/weekly agenda, the sums cover a single day; - in all other views they cover the entire block. - - It is important to realize that the agenda may show the same entry - _twice_—for example as scheduled and as a deadline—and it may show - two entries from the same hierarchy (for example a _parent_ and its - _child_). In these cases, the summation in the agenda leads to - incorrect results because some values count double. - - 3. When the column view in the agenda shows the ‘CLOCKSUM’ property, - that is always the entire clocked time for this item. So even in - the daily/weekly agenda, the clocksum listed in column view may - originate from times outside the current view. This has the - advantage that you can compare these values with a column listing - the planned total effort for a task—one of the major applications - for column view in the agenda. If you want information about - clocked time in the displayed period use clock table mode (press - ‘R’ in the agenda). - - 4. When the column view in the agenda shows the ‘CLOCKSUM_T’ property, - that is always today’s clocked time for this item. So even in the - weekly agenda, the clocksum listed in column view only originates - from today. This lets you compare the time you spent on a task for - today, with the time already spent—via ‘CLOCKSUM’—and with the - planned total effort for it. - - -File: org.info, Node: Markup for Rich Contents, Next: Exporting, Prev: Agenda Views, Up: Top - -12 Markup for Rich Contents -*************************** - -Org is primarily about organizing and searching through your plain-text -notes. However, it also provides a lightweight yet robust markup -language for rich text formatting and more. For instance, you may want -to center or emphasize text. Or you may need to insert a formula or -image in your writing. Org offers syntax for all of this and more. -Used in conjunction with the export framework (see *note Exporting::), -you can author beautiful documents in Org—like the fine manual you are -currently reading. - -* Menu: - -* Paragraphs:: The basic unit of text. -* Emphasis and Monospace:: Bold, italic, etc. -* Subscripts and Superscripts:: Simple syntax for raising/lowering text. -* Special Symbols:: Greek letters and other symbols. -* Embedded LaTeX:: LaTeX can be freely used inside Org documents. -* Literal Examples:: Source code examples with special formatting. -* Images:: Display an image. -* Captions:: Describe tables, images... -* Horizontal Rules:: Make a line. -* Creating Footnotes:: Edit and read footnotes. - - -File: org.info, Node: Paragraphs, Next: Emphasis and Monospace, Up: Markup for Rich Contents - -12.1 Paragraphs -=============== - -Paragraphs are separated by at least one empty line. If you need to -enforce a line break within a paragraph, use ‘\\’ at the end of a line. - - To preserve the line breaks, indentation and blank lines in a region, -but otherwise use normal formatting, you can use this construct, which -can also be used to format poetry. - - #+BEGIN_VERSE - Great clouds overhead - Tiny black birds rise and fall - Snow covers Emacs - - ---AlexSchroeder - #+END_VERSE - - When quoting a passage from another document, it is customary to -format this as a paragraph that is indented on both the left and the -right margin. You can include quotations in Org documents like this: - - #+BEGIN_QUOTE - Everything should be made as simple as possible, - but not any simpler ---Albert Einstein - #+END_QUOTE - - If you would like to center some text, do it like this: - - #+BEGIN_CENTER - Everything should be made as simple as possible, \\ - but not any simpler - #+END_CENTER - - -File: org.info, Node: Emphasis and Monospace, Next: Subscripts and Superscripts, Prev: Paragraphs, Up: Markup for Rich Contents - -12.2 Emphasis and Monospace -=========================== - -You can make words ‘*bold*’, ‘/italic/’, ‘_underlined_’, ‘=verbatim=’ -and ‘~code~’, and, if you must, ‘+strike-through+’. Text in the code -and verbatim string is not processed for Org specific syntax; it is -exported verbatim. - - To turn off fontification for marked up text, you can set -‘org-fontify-emphasized-text’ to ‘nil’. To narrow down the list of -available markup syntax, you can customize ‘org-emphasis-alist’. - - Sometimes, when marked text also contains the marker character -itself, the result may be unsettling. For example, - - /One may expect this whole sentence to be italicized, but the - following ~user/?variable~ contains =/= character, which effectively - stops emphasis there./ - - You can use zero width space to help Org sorting out the ambiguity. -See *note Escape Character:: for more details. - - -File: org.info, Node: Subscripts and Superscripts, Next: Special Symbols, Prev: Emphasis and Monospace, Up: Markup for Rich Contents - -12.3 Subscripts and Superscripts -================================ - -‘^’ and ‘_’ are used to indicate super- and subscripts. To increase the -readability of ASCII text, it is not necessary, but OK, to surround -multi-character sub- and superscripts with curly braces. For example - - The radius of the sun is R_sun = 6.96 x 10^8 m. On the other hand, - the radius of Alpha Centauri is R_{Alpha Centauri} = 1.28 x R_{sun}. - - If you write a text where the underscore is often used in a different -context, Org’s convention to always interpret these as subscripts can -get in your way. Configure the variable ‘org-use-sub-superscripts’ to -change this convention. For example, when setting this variable to -‘{}’, ‘a_b’ is not interpreted as a subscript, but ‘a_{b}’ is. - - You can set ‘org-use-sub-superscripts’ in a file using the export -option ‘^:’ (see *note Export Settings::). For example, ‘#+OPTIONS: -^:{}’ sets ‘org-use-sub-superscripts’ to ‘{}’ and limits super- and -subscripts to the curly bracket notation. - - You can also toggle the visual display of super- and subscripts: - -‘C-c C-x \’ (‘org-toggle-pretty-entities’) - This command formats sub- and superscripts in a WYSIWYM way. - - Set both ‘org-pretty-entities’ and -‘org-pretty-entities-include-sub-superscripts’ to ‘t’ to start with -super- and subscripts _visually_ interpreted as specified by the option -‘org-use-sub-superscripts’. - - -File: org.info, Node: Special Symbols, Next: Embedded LaTeX, Prev: Subscripts and Superscripts, Up: Markup for Rich Contents - -12.4 Special Symbols -==================== - -You can use LaTeX-like syntax to insert special symbols—named -entities—like ‘\alpha’ to indicate the Greek letter, or ‘\to’ to -indicate an arrow. Completion for these symbols is available, just type -‘\’ and maybe a few letters, and press ‘M-<TAB>’ to see possible -completions. If you need such a symbol inside a word, terminate it with -a pair of curly brackets. For example - - Pro tip: Given a circle \Gamma of diameter d, the length of its - circumference is \pi{}d. - - A large number of entities is provided, with names taken from both -HTML and LaTeX; you can comfortably browse the complete list from a -dedicated buffer using the command ‘org-entities-help’. It is also -possible to provide your own special symbols in the variable -‘org-entities-user’. - - During export, these symbols are transformed into the native format -of the exporter back-end. Strings like ‘\alpha’ are exported as -‘α’ in the HTML output, and as ‘\(\alpha\)’ in the LaTeX output. -Similarly, ‘\nbsp’ becomes ‘ ’ in HTML and ‘~’ in LaTeX. - - If you would like to see entities displayed as UTF-8 characters, use -the following command(1): - -‘C-c C-x \’ (‘org-toggle-pretty-entities’) - - Toggle display of entities as UTF-8 characters. This does not - change the buffer content which remains plain ASCII, but it - overlays the UTF-8 character for display purposes only. - - In addition to regular entities defined above, Org exports in a -special way(2) the following commonly used character combinations: ‘\-’ -is treated as a shy hyphen, ‘--’ and ‘---’ are converted into dashes, -and ‘...’ becomes a compact set of dots. - - ---------- Footnotes ---------- - - (1) You can turn this on by default by setting the variable -‘org-pretty-entities’, or on a per-file base with the ‘STARTUP’ option -‘entitiespretty’. - - (2) This behavior can be disabled with ‘-’ export setting (see *note -Export Settings::). - - -File: org.info, Node: Embedded LaTeX, Next: Literal Examples, Prev: Special Symbols, Up: Markup for Rich Contents - -12.5 Embedded LaTeX -=================== - -Plain ASCII is normally sufficient for almost all note taking. -Exceptions include scientific notes, which often require mathematical -symbols and the occasional formula. LaTeX(1) is widely used to typeset -scientific documents. Org mode supports embedding LaTeX code into its -files, because many academics are used to writing and reading LaTeX -source code, and because it can be readily processed to produce pretty -output for a number of export back-ends. - -* Menu: - -* LaTeX fragments:: Complex formulas made easy. -* Previewing LaTeX fragments:: What will this snippet look like? -* CDLaTeX mode:: Speed up entering of formulas. - - ---------- Footnotes ---------- - - (1) LaTeX is a macro system based on Donald E. Knuth’s TeX system. -Many of the features described here as “LaTeX” are really from TeX, but -for simplicity I am blurring this distinction. - - -File: org.info, Node: LaTeX fragments, Next: Previewing LaTeX fragments, Up: Embedded LaTeX - -12.5.1 LaTeX fragments ----------------------- - -Org mode can contain LaTeX math fragments, and it supports ways to -process these for several export back-ends. When exporting to LaTeX, -the code is left as it is. When exporting to HTML, Org can use either -MathJax (https://www.mathjax.org) (see *note Math formatting in HTML -export::) or transcode the math into images (see *note Previewing LaTeX -fragments::). - - LaTeX fragments do not need any special marking at all. The -following snippets are identified as LaTeX source code: - - • Environments of any kind(1). The only requirement is that the - ‘\begin’ statement appears on a new line, preceded by only - whitespace. - - • Text within the usual LaTeX math delimiters. To avoid conflicts - with currency specifications, single ‘$’ characters are only - recognized as math delimiters if the enclosed text contains at most - two line breaks, is directly attached to the ‘$’ characters with no - whitespace in between, and if the closing ‘$’ is followed by - whitespace, punctuation or a dash. For the other delimiters, there - is no such restriction, so when in doubt, use ‘\(...\)’ as inline - math delimiters. - -For example: - - \begin{equation} % arbitrary environments, - x=\sqrt{b} % even tables, figures - \end{equation} % etc - - If $a^2=b$ and \( b=2 \), then the solution must be - either $$ a=+\sqrt{2} $$ or \[ a=-\sqrt{2} \]. - - LaTeX processing can be configured with the variable -‘org-export-with-latex’. The default setting is ‘t’ which means MathJax -for HTML, and no processing for ASCII and LaTeX back-ends. You can also -set this variable on a per-file basis using one of these lines: - -‘#+OPTIONS: tex:t’ Do the right thing automatically (MathJax) -‘#+OPTIONS: tex:nil’ Do not process LaTeX fragments at all -‘#+OPTIONS: tex:verbatim’ Verbatim export, for jsMath or so - - ---------- Footnotes ---------- - - (1) When MathJax is used, only the environments recognized by MathJax -are processed. When dvipng, dvisvgm, or ImageMagick suite is used to -create images, any LaTeX environment is handled. - - -File: org.info, Node: Previewing LaTeX fragments, Next: CDLaTeX mode, Prev: LaTeX fragments, Up: Embedded LaTeX - -12.5.2 Previewing LaTeX fragments ---------------------------------- - -If you have a working LaTeX installation and ‘dvipng’, ‘dvisvgm’ or -‘convert’ installed(1), LaTeX fragments can be processed to produce -images of the typeset expressions to be used for inclusion while -exporting to HTML (see *note LaTeX fragments::), or for inline -previewing within Org mode. - - You can customize the variables ‘org-format-latex-options’ and -‘org-format-latex-header’ to influence some aspects of the preview. In -particular, the ‘:scale’ (and for HTML export, ‘:html-scale’) property -of the former can be used to adjust the size of the preview images. - -‘C-c C-x C-l’ (‘org-latex-preview’) - - Produce a preview image of the LaTeX fragment at point and overlay - it over the source code. If there is no fragment at point, process - all fragments in the current entry—between two headlines. - - When called with a single prefix argument, clear all images in the - current entry. Two prefix arguments produce a preview image for - all fragments in the buffer, while three of them clear all the - images in that buffer. - - You can turn on the previewing of all LaTeX fragments in a file with - - #+STARTUP: latexpreview - - To disable it, simply use - - #+STARTUP: nolatexpreview - - ---------- Footnotes ---------- - - (1) These are respectively available at -<http://sourceforge.net/projects/dvipng/>, <http://dvisvgm.bplaced.net/> -and from the ImageMagick suite. Choose the converter by setting the -variable ‘org-preview-latex-default-process’ accordingly. - - -File: org.info, Node: CDLaTeX mode, Prev: Previewing LaTeX fragments, Up: Embedded LaTeX - -12.5.3 Using CDLaTeX to enter math ----------------------------------- - -CDLaTeX mode is a minor mode that is normally used in combination with a -major LaTeX mode like AUCTeX in order to speed-up insertion of -environments and math templates. Inside Org mode, you can make use of -some of the features of CDLaTeX mode. You need to install ‘cdlatex.el’ -and ‘texmathp.el’ (the latter comes also with AUCTeX) using MELPA -(https://melpa.org/) with the Emacs packaging system -(https://www.gnu.org/software/emacs/manual/html_node/emacs/Package-Installation.html) -or alternatively from -<https://staff.fnwi.uva.nl/c.dominik/Tools/cdlatex/>. Do not use -CDLaTeX mode itself under Org mode, but use the special version Org -CDLaTeX minor mode that comes as part of Org. Turn it on for the -current buffer with ‘M-x org-cdlatex-mode’, or for all Org files with - - (add-hook 'org-mode-hook #'turn-on-org-cdlatex) - - When this mode is enabled, the following features are present (for -more details see the documentation of CDLaTeX mode): - -‘C-c {’ - - Insert an environment template. - -‘<TAB>’ - - The ‘<TAB>’ key expands the template if point is inside a LaTeX - fragment(1). For example, ‘<TAB>’ expands ‘fr’ to ‘\frac{}{}’ and - position point correctly inside the first brace. Another ‘<TAB>’ - gets you into the second brace. - - Even outside fragments, ‘<TAB>’ expands environment abbreviations - at the beginning of a line. For example, if you write ‘equ’ at the - beginning of a line and press ‘<TAB>’, this abbreviation is - expanded to an ‘equation’ environment. To get a list of all - abbreviations, type ‘M-x cdlatex-command-help’. - -‘^’ -‘_’ - - Pressing ‘_’ and ‘^’ inside a LaTeX fragment inserts these - characters together with a pair of braces. If you use ‘<TAB>’ to - move out of the braces, and if the braces surround only a single - character or macro, they are removed again (depending on the - variable ‘cdlatex-simplify-sub-super-scripts’). - -‘`’ - - Pressing the backquote followed by a character inserts math macros, - also outside LaTeX fragments. If you wait more than 1.5 seconds - after the backquote, a help window pops up. - -‘'’ - - Pressing the single-quote followed by another character modifies - the symbol before point with an accent or a font. If you wait more - than 1.5 seconds after the single-quote, a help window pops up. - Character modification works only inside LaTeX fragments; outside - the quote is normal. - - ---------- Footnotes ---------- - - (1) Org mode has a method to test if point is inside such a fragment, -see the documentation of the function ‘org-inside-LaTeX-fragment-p’. - - -File: org.info, Node: Literal Examples, Next: Images, Prev: Embedded LaTeX, Up: Markup for Rich Contents - -12.6 Literal Examples -===================== - -You can include literal examples that should not be subjected to markup. -Such examples are typeset in monospace, so this is well suited for -source code and similar examples. - - #+BEGIN_EXAMPLE - Some example from a text file. - #+END_EXAMPLE - - There is one limitation, however. You must insert a comma right -before lines starting with either ‘*’, ‘,*’, ‘#+’ or ‘,#+’, as those may -be interpreted as outlines nodes or some other special syntax. Org -transparently strips these additional commas whenever it accesses the -contents of the block. - - #+BEGIN_EXAMPLE - ,* I am no real headline - #+END_EXAMPLE - - For simplicity when using small examples, you can also start the -example lines with a colon followed by a space. There may also be -additional whitespace before the colon: - - Here is an example - : Some example from a text file. - - If the example is source code from a programming language, or any -other text that can be marked up by Font Lock in Emacs, you can ask for -the example to look like the fontified Emacs buffer(1). This is done -with the code block, where you also need to specify the name of the -major mode that should be used to fontify the example(2), see *note -Structure Templates:: for shortcuts to easily insert code blocks. - - #+BEGIN_SRC emacs-lisp - (defun org-xor (a b) - "Exclusive or." - (if a (not b) b)) - #+END_SRC - - Both in ‘example’ and in ‘src’ snippets, you can add a ‘-n’ switch to -the end of the ‘#+BEGIN’ line, to get the lines of the example numbered. -The ‘-n’ takes an optional numeric argument specifying the starting line -number of the block. If you use a ‘+n’ switch, the numbering from the -previous numbered snippet is continued in the current one. The ‘+n’ -switch can also take a numeric argument. This adds the value of the -argument to the last line of the previous block to determine the -starting line number. - - #+BEGIN_SRC emacs-lisp -n 20 - ;; This exports with line number 20. - (message "This is line 21") - #+END_SRC - - #+BEGIN_SRC emacs-lisp +n 10 - ;; This is listed as line 31. - (message "This is line 32") - #+END_SRC - - In literal examples, Org interprets strings like ‘(ref:name)’ as -labels, and use them as targets for special hyperlinks like -‘[[(name)]]’—i.e., the reference name enclosed in single parenthesis. -In HTML, hovering the mouse over such a link remote-highlights the -corresponding code line, which is kind of cool. - - You can also add a ‘-r’ switch which _removes_ the labels from the -source code(3). With the ‘-n’ switch, links to these references are -labeled by the line numbers from the code listing. Otherwise links use -the labels with no parentheses. Here is an example: - - #+BEGIN_SRC emacs-lisp -n -r - (save-excursion (ref:sc) - (goto-char (point-min)) (ref:jump) - #+END_SRC - In line [[(sc)]] we remember the current position. [[(jump)][Line (jump)]] - jumps to point-min. - - Source code and examples may be _indented_ in order to align nicely -with the surrounding text, and in particular with plain list structure -(see *note Plain Lists::). By default, Org only retains the relative -indentation between lines, e.g., when exporting the contents of the -block. However, you can use the ‘-i’ switch to also preserve the global -indentation, if it does matter. See *note Editing Source Code::. - - If the syntax for the label format conflicts with the language -syntax, use a ‘-l’ switch to change the format, for example - - #+BEGIN_SRC pascal -n -r -l "((%s))" - -See also the variable ‘org-coderef-label-format’. - - HTML export also allows examples to be published as text areas (see -*note Text areas in HTML export::). - - Because the ‘#+BEGIN’ ... ‘#+END’ patterns need to be added so often, -a shortcut is provided (see *note Structure Templates::). - -‘C-c '’ (‘org-edit-special’) - Edit the source code example at point in its native mode. This - works by switching to a temporary buffer with the source code. You - need to exit by pressing ‘C-c '’ again. The edited version then - replaces the old version in the Org buffer. Fixed-width - regions—where each line starts with a colon followed by a space—are - edited using Artist mode(4) to allow creating ASCII drawings - easily. Using this command in an empty line creates a new - fixed-width region. - - Calling ‘org-store-link’ (see *note Handling Links::) while editing a -source code example in a temporary buffer created with ‘C-c '’ prompts -for a label. Make sure that it is unique in the current buffer, and -insert it with the proper formatting like ‘(ref:label)’ at the end of -the current line. Then the label is stored as a link ‘(label)’, for -retrieval with ‘C-c C-l’. - - ---------- Footnotes ---------- - - (1) This works automatically for the HTML backend (it requires -version 1.34 of the ‘htmlize.el’ package, which you need to install). -Fontified code chunks in LaTeX can be achieved using either the listings -(https://www.ctan.org/pkg/listings) package or the minted -(https://www.ctan.org/pkg/minted) package. Refer to -‘org-latex-listings’ for details. - - (2) Source code in code blocks may also be evaluated either -interactively or on export. See *note Working with Source Code:: for -more information on evaluating code blocks. - - (3) Adding ‘-k’ to ‘-n -r’ _keeps_ the labels in the source code -while using line numbers for the links, which might be useful to explain -those in an Org mode example code. - - (4) You may select a different mode with the variable -‘org-edit-fixed-width-region-mode’. - - -File: org.info, Node: Images, Next: Captions, Prev: Literal Examples, Up: Markup for Rich Contents - -12.7 Images -=========== - -An image is a link to an image file(1) that does not have a description -part, for example - - ./img/cat.jpg - - If you wish to define a caption for the image (see *note Captions::) -and maybe a label for internal cross references (see *note Internal -Links::), make sure that the link is on a line by itself and precede it -with ‘CAPTION’ and ‘NAME’ keywords as follows: - - #+CAPTION: This is the caption for the next figure link (or table) - #+NAME: fig:SED-HR4049 - [[./img/a.jpg]] - - Such images can be displayed within the buffer with the following -command: - -‘C-c C-x C-v’ (‘org-toggle-inline-images’) - Toggle the inline display of linked images. When called with a - prefix argument, also display images that do have a link - description. You can ask for inline images to be displayed at - startup by configuring the variable - ‘org-startup-with-inline-images’(2). - - ---------- Footnotes ---------- - - (1) What Emacs considers to be an image depends on -‘image-file-name-extensions’ and ‘image-file-name-regexps’. - - (2) The variable ‘org-startup-with-inline-images’ can be set within a -buffer with the ‘STARTUP’ options ‘inlineimages’ and ‘noinlineimages’. - - -File: org.info, Node: Captions, Next: Horizontal Rules, Prev: Images, Up: Markup for Rich Contents - -12.8 Captions -============= - -You can assign a caption to a specific part of a document by inserting a -‘CAPTION’ keyword immediately before it: - - #+CAPTION: This is the caption for the next table (or link) - | ... | ... | - |-----+-----| - - Optionally, the caption can take the form: - - #+CAPTION[Short caption]: Longer caption. - - Even though images and tables are prominent examples of captioned -structures, the same caption mechanism can apply to many others—e.g., -LaTeX equations, source code blocks. Depending on the export back-end, -those may or may not be handled. - - -File: org.info, Node: Horizontal Rules, Next: Creating Footnotes, Prev: Captions, Up: Markup for Rich Contents - -12.9 Horizontal Rules -===================== - -A line consisting of only dashes, and at least 5 of them, is exported as -a horizontal line. - - -File: org.info, Node: Creating Footnotes, Prev: Horizontal Rules, Up: Markup for Rich Contents - -12.10 Creating Footnotes -======================== - -A footnote is started by a footnote marker in square brackets in column -0, no indentation allowed. It ends at the next footnote definition, -headline, or after two consecutive empty lines. The footnote reference -is simply the marker in square brackets, inside text. Markers always -start with ‘fn:’. For example: - - The Org homepage[fn:1] now looks a lot better than it used to. - ... - [fn:1] The link is: https://orgmode.org - - Org mode extends the number-based syntax to _named_ footnotes and -optional inline definition. Here are the valid references: - -‘[fn:NAME]’ - A named footnote reference, where NAME is a unique label word, or, - for simplicity of automatic creation, a number. - -‘[fn:: This is the inline definition of this footnote]’ - An anonymous footnote where the definition is given directly at the - reference point. - -‘[fn:NAME: a definition]’ - An inline definition of a footnote, which also specifies a name for - the note. Since Org allows multiple references to the same note, - you can then use ‘[fn:NAME]’ to create additional references. - - Footnote labels can be created automatically, or you can create names -yourself. This is handled by the variable ‘org-footnote-auto-label’ and -its corresponding ‘STARTUP’ keywords. See the docstring of that -variable for details. - - The following command handles footnotes: - -‘C-c C-x f’ - The footnote action command. - - When point is on a footnote reference, jump to the definition. - When it is at a definition, jump to the—first—reference. - - Otherwise, create a new footnote. Depending on the variable - ‘org-footnote-define-inline’(1), the definition is placed right - into the text as part of the reference, or separately into the - location determined by the variable ‘org-footnote-section’. - - When this command is called with a prefix argument, a menu of - additional options is offered: - - ‘s’ Sort the footnote definitions by reference sequence. - ‘r’ Renumber the simple ‘fn:N’ footnotes. - ‘S’ Short for first ‘r’, then ‘s’ action. - ‘n’ Rename all footnotes into a ‘fn:1’ ... ‘fn:n’ sequence. - ‘d’ Delete the footnote at point, including definition and - references. - - Depending on the variable ‘org-footnote-auto-adjust’(2), - renumbering and sorting footnotes can be automatic after each - insertion or deletion. - -‘C-c C-c’ - If point is on a footnote reference, jump to the definition. If it - is at the definition, jump back to the reference. When called at a - footnote location with a prefix argument, offer the same menu as - ‘C-c C-x f’. - -‘C-c C-o’ or ‘mouse-1/2’ - Footnote labels are also links to the corresponding definition or - reference, and you can use the usual commands to follow these - links. - - ---------- Footnotes ---------- - - (1) The corresponding in-buffer setting is: ‘#+STARTUP: fninline’ or -‘#+STARTUP: nofninline’. - - (2) The corresponding in-buffer options are ‘#+STARTUP: fnadjust’ and -‘#+STARTUP: nofnadjust’. - - -File: org.info, Node: Exporting, Next: Publishing, Prev: Markup for Rich Contents, Up: Top - -13 Exporting -************ - -At some point you might want to print your notes, publish them on the -web, or share them with people not using Org. Org can convert and -export documents to a variety of other formats while retaining as much -structure (see *note Document Structure::) and markup (see *note Markup -for Rich Contents::) as possible. - - The libraries responsible for translating Org files to other formats -are called _back-ends_. Org ships with support for the following -back-ends: - - • _ascii_ (ASCII format) - • _beamer_ (LaTeX Beamer format) - • _html_ (HTML format) - • _icalendar_ (iCalendar format) - • _latex_ (LaTeX format) - • _md_ (Markdown format) - • _odt_ (OpenDocument Text format) - • _org_ (Org format) - • _texinfo_ (Texinfo format) - • _man_ (Man page format) - - Users can install libraries for additional formats from the Emacs -packaging system. For easy discovery, these packages have a common -naming scheme: ‘ox-NAME’, where NAME is a format. For example, -‘ox-koma-letter’ for _koma-letter_ back-end. More libraries can be -found in the ‘org-contrib’ repository (see *note Installation::). - - Org only loads back-ends for the following formats by default: ASCII, -HTML, iCalendar, LaTeX, and ODT. Additional back-ends can be loaded in -either of two ways: by configuring the ‘org-export-backends’ variable, -or by requiring libraries in the Emacs init file. For example, to load -the Markdown back-end, add this to your Emacs config: - - (require 'ox-md) - -* Menu: - -* The Export Dispatcher:: The main interface. -* Export Settings:: Common export settings. -* Table of Contents:: The if and where of the table of contents. -* Include Files:: Include additional files into a document. -* Macro Replacement:: Use macros to create templates. -* Comment Lines:: What will not be exported. -* ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding. -* Beamer Export:: Producing presentations and slides. -* HTML Export:: Exporting to HTML. -* LaTeX Export:: Exporting to LaTeX and processing to PDF. -* Markdown Export:: Exporting to Markdown. -* OpenDocument Text Export:: Exporting to OpenDocument Text. -* Org Export:: Exporting to Org. -* Texinfo Export:: Exporting to Texinfo. -* iCalendar Export:: Exporting to iCalendar. -* Other Built-in Back-ends:: Exporting to a man page. -* Advanced Export Configuration:: Fine-tuning the export output. -* Export in Foreign Buffers:: Author tables and lists in Org syntax. - - -File: org.info, Node: The Export Dispatcher, Next: Export Settings, Up: Exporting - -13.1 The Export Dispatcher -========================== - -The export dispatcher is the main interface for Org’s exports. A -hierarchical menu presents the currently configured export formats. -Options are shown as easy toggle switches on the same screen. - - Org also has a minimal prompt interface for the export dispatcher. -When the variable ‘org-export-dispatch-use-expert-ui’ is set to a -non-‘nil’ value, Org prompts in the minibuffer. To switch back to the -hierarchical menu, press ‘?’. - -‘C-c C-e’ (‘org-export’) - - Invokes the export dispatcher interface. The options show default - settings. The ‘C-u’ prefix argument preserves options from the - previous export, including any sub-tree selections. - - Org exports the entire buffer by default. If the Org buffer has an -active region, then Org exports just that region. - - Within the dispatcher interface, the following key combinations can -further alter what is exported, and how. - -‘C-a’ - - Toggle asynchronous export. Asynchronous export uses an external - Emacs process with a specially configured initialization file to - complete the exporting process in the background, without tying-up - Emacs. This is particularly useful when exporting long documents. - - Output from an asynchronous export is saved on the _export stack_. - To view this stack, call the export dispatcher with a double ‘C-u’ - prefix argument. If already in the export dispatcher menu, ‘&’ - displays the stack. - - You can make asynchronous export the default by setting - ‘org-export-in-background’. - - You can set the initialization file used by the background process - by setting ‘org-export-async-init-file’. - -‘C-b’ - - Toggle body-only export. Useful for excluding headers and footers - in the export. Affects only those back-end formats that have - sections like ‘<head>...</head>’ in HTML. - -‘C-s’ - - Toggle sub-tree export. When turned on, Org exports only the - sub-tree starting from point position at the time the export - dispatcher was invoked. Org uses the top heading of this sub-tree - as the document’s title. If point is not on a heading, Org uses - the nearest enclosing header. If point is in the document - preamble, Org signals an error and aborts export. - - To make sub-tree export the default, customize the variable - ‘org-export-initial-scope’. - -‘C-v’ - - Toggle visible-only export. This is useful for exporting only - certain parts of an Org document by adjusting the visibility of - particular headings. See also *note Sparse Trees::. - - -File: org.info, Node: Export Settings, Next: Table of Contents, Prev: The Export Dispatcher, Up: Exporting - -13.2 Export Settings -==================== - -Export options can be set: globally with variables; for an individual -file by making variables buffer-local with in-buffer settings (see *note -In-buffer Settings::); by setting individual keywords or specifying them -in compact form with the ‘OPTIONS’ keyword; or for a tree by setting -properties (see *note Properties and Columns::). Options set at a -specific level override options set at a more general level. - - In-buffer settings may appear anywhere in the file, either directly -or indirectly through a file included using ‘#+SETUPFILE: filename or -URL’ syntax. Option keyword sets tailored to a particular back-end can -be inserted from the export dispatcher (see *note The Export -Dispatcher::) using the ‘Insert template’ command by pressing ‘#’. To -insert keywords individually, a good way to make sure the keyword is -correct is to type ‘#+’ and then to use ‘M-<TAB>’(1) for completion. - - The export keywords available for every back-end, and their -equivalent global variables, include: - -‘AUTHOR’ - The document author (‘user-full-name’). - -‘CREATOR’ - Entity responsible for output generation - (‘org-export-creator-string’). - -‘DATE’ - A date or a time-stamp(2). - -‘EMAIL’ - The email address (‘user-mail-address’). - -‘LANGUAGE’ - Language to use for translating certain strings - (‘org-export-default-language’). With ‘#+LANGUAGE: fr’, for - example, Org translates ‘Table of contents’ to the French ‘Table - des matières’(3). - -‘SELECT_TAGS’ - The default value is ‘("export")’. When a tree is tagged with - ‘export’ (‘org-export-select-tags’), Org selects that tree and its - sub-trees for export. Org excludes trees with ‘noexport’ tags, see - below. When selectively exporting files with ‘export’ tags set, - Org does not export any text that appears before the first - headline. - -‘EXCLUDE_TAGS’ - The default value is ‘("noexport")’. When a tree is tagged with - ‘noexport’ (‘org-export-exclude-tags’), Org excludes that tree and - its sub-trees from export. Entries tagged with ‘noexport’ are - unconditionally excluded from the export, even if they have an - ‘export’ tag. Even if a sub-tree is not exported, Org executes any - code blocks contained there. - -‘TITLE’ - Org displays this title. For long titles, use multiple ‘#+TITLE’ - lines. - -‘EXPORT_FILE_NAME’ - The name of the output file to be generated. Otherwise, Org - generates the file name based on the buffer name and the extension - based on the back-end format. - - The ‘OPTIONS’ keyword is a compact form. To configure multiple -options, use several ‘OPTIONS’ lines. ‘OPTIONS’ recognizes the -following arguments. - -‘'’ - Toggle smart quotes (‘org-export-with-smart-quotes’). Depending on - the language used, when activated, Org treats pairs of double - quotes as primary quotes, pairs of single quotes as secondary - quotes, and single quote marks as apostrophes. - -‘*’ - Toggle emphasized text (‘org-export-with-emphasize’). - -‘-’ - Toggle conversion of special strings - (‘org-export-with-special-strings’). - -‘:’ - Toggle fixed-width sections (‘org-export-with-fixed-width’). - -‘<’ - Toggle inclusion of time/date active/inactive stamps - (‘org-export-with-timestamps’). - -‘\n’ - Toggles whether to preserve line breaks - (‘org-export-preserve-breaks’). - -‘^’ - Toggle TeX-like syntax for sub- and superscripts. If you write - ‘^:{}’, ‘a_{b}’ is interpreted, but the simple ‘a_b’ is left as it - is (‘org-export-with-sub-superscripts’). - -‘arch’ - Configure how archived trees are exported. When set to ‘headline’, - the export process skips the contents and processes only the - headlines (‘org-export-with-archived-trees’). - -‘author’ - Toggle inclusion of author name into exported file - (‘org-export-with-author’). - -‘broken-links’ - Toggles if Org should continue exporting upon finding a broken - internal link. When set to ‘mark’, Org clearly marks the problem - link in the output (‘org-export-with-broken-links’). - -‘c’ - Toggle inclusion of ‘CLOCK’ keywords (‘org-export-with-clocks’). - -‘creator’ - Toggle inclusion of creator information in the exported file - (‘org-export-with-creator’). - -‘d’ - Toggles inclusion of drawers, or list of drawers to include, or - list of drawers to exclude (‘org-export-with-drawers’). - -‘date’ - Toggle inclusion of a date into exported file - (‘org-export-with-date’). - -‘e’ - Toggle inclusion of entities (‘org-export-with-entities’). - -‘email’ - Toggle inclusion of the author’s e-mail into exported file - (‘org-export-with-email’). - -‘f’ - Toggle the inclusion of footnotes (‘org-export-with-footnotes’). - -‘H’ - Set the number of headline levels for export - (‘org-export-headline-levels’). Below that level, headlines are - treated differently. In most back-ends, they become list items. - -‘inline’ - Toggle inclusion of inlinetasks (‘org-export-with-inlinetasks’). - -‘num’ - Toggle section-numbers (‘org-export-with-section-numbers’). When - set to number N, Org numbers only those headlines at level N or - above. Set ‘UNNUMBERED’ property to non-‘nil’ to disable numbering - of heading and subheadings entirely. Moreover, when the value is - ‘notoc’ the headline, and all its children, do not appear in the - table of contents either (see *note Table of Contents::). - -‘p’ - Toggle export of planning information (‘org-export-with-planning’). - “Planning information” comes from lines located right after the - headline and contain any combination of these cookies: ‘SCHEDULED’, - ‘DEADLINE’, or ‘CLOSED’. - -‘pri’ - Toggle inclusion of priority cookies (‘org-export-with-priority’). - -‘prop’ - Toggle inclusion of property drawers, or list the properties to - include (‘org-export-with-properties’). - -‘stat’ - Toggle inclusion of statistics cookies - (‘org-export-with-statistics-cookies’). - -‘tags’ - Toggle inclusion of tags, may also be ‘not-in-toc’ - (‘org-export-with-tags’). - -‘tasks’ - Toggle inclusion of tasks (TODO items); or ‘nil’ to remove all - tasks; or ‘todo’ to remove done tasks; or list the keywords to keep - (‘org-export-with-tasks’). - -‘tex’ - ‘nil’ does not export; ‘t’ exports; ‘verbatim’ keeps everything in - verbatim (‘org-export-with-latex’). - -‘timestamp’ - Toggle inclusion of the creation time in the exported file - (‘org-export-time-stamp-file’). - -‘title’ - Toggle inclusion of title (‘org-export-with-title’). - -‘toc’ - Toggle inclusion of the table of contents, or set the level limit - (‘org-export-with-toc’). - -‘todo’ - Toggle inclusion of TODO keywords into exported text - (‘org-export-with-todo-keywords’). - -‘|’ - Toggle inclusion of tables (‘org-export-with-tables’). - - When exporting sub-trees, special node properties can override the -above keywords. These properties have an ‘EXPORT_’ prefix. For -example, ‘DATE’ becomes, ‘EXPORT_DATE’ when used for a specific -sub-tree. Except for ‘SETUPFILE’, all other keywords listed above have -an ‘EXPORT_’ equivalent. - - If ‘org-export-allow-bind-keywords’ is non-‘nil’, Emacs variables can -become buffer-local during export by using the ‘BIND’ keyword. Its -syntax is ‘#+BIND: variable value’. This is particularly useful for -in-buffer settings that cannot be changed using keywords. - - ---------- Footnotes ---------- - - (1) Many desktops intercept ‘M-<TAB>’ to switch windows. Use ‘C-M-i’ -or ‘<ESC> <TAB>’ instead. - - (2) The variable ‘org-export-date-timestamp-format’ defines how this -timestamp are exported. - - (3) For export to LaTeX format—or LaTeX-related formats such as -Beamer—, the ‘org-latex-package-alist’ variable needs further -configuration. See *note LaTeX specific export settings::. - - -File: org.info, Node: Table of Contents, Next: Include Files, Prev: Export Settings, Up: Exporting - -13.3 Table of Contents -====================== - -The table of contents includes all headlines in the document. Its depth -is therefore the same as the headline levels in the file. If you need -to use a different depth, or turn it off entirely, set the -‘org-export-with-toc’ variable accordingly. You can achieve the same on -a per file basis, using the following ‘toc’ item in ‘OPTIONS’ keyword: - - #+OPTIONS: toc:2 (only include two levels in TOC) - #+OPTIONS: toc:nil (no default TOC at all) - - Org includes both numbered and unnumbered headlines in the table of -contents(1). If you need to exclude an unnumbered headline, along with -all its children, set the ‘UNNUMBERED’ property to ‘notoc’ value. - - * Subtree not numbered, not in table of contents either - :PROPERTIES: - :UNNUMBERED: notoc - :END: - - Org normally inserts the table of contents directly before the first -headline of the file. To move the table of contents to a different -location, first turn off the default with ‘org-export-with-toc’ variable -or with ‘#+OPTIONS: toc:nil’. Then insert ‘#+TOC: headlines N’ at the -desired location(s). - - #+OPTIONS: toc:nil - ... - #+TOC: headlines 2 - - To adjust the table of contents depth for a specific section of the -Org document, append an additional ‘local’ parameter. This parameter -becomes a relative depth for the current level. The following example -inserts a local table of contents, with direct children only. - - * Section - #+TOC: headlines 1 local - - Note that for this feature to work properly in LaTeX export, the Org -file requires the inclusion of the titletoc package. Because of -compatibility issues, titletoc has to be loaded _before_ hyperref. -Customize the ‘org-latex-default-packages-alist’ variable. - - The following example inserts a table of contents that links to the -children of the specified target. - - * Target - :PROPERTIES: - :CUSTOM_ID: TargetSection - :END: - ** Heading A - ** Heading B - * Another section - #+TOC: headlines 1 :target #TargetSection - - The ‘:target’ attribute is supported in HTML, Markdown, ODT, and -ASCII export. - - Use the ‘TOC’ keyword to generate list of tables—respectively, all -listings—with captions. - - #+TOC: listings - #+TOC: tables - - Normally Org uses the headline for its entry in the table of -contents. But with ‘ALT_TITLE’ property, a different entry can be -specified for the table of contents. - - ---------- Footnotes ---------- - - (1) At the moment, some export back-ends do not obey this -specification. For example, LaTeX export excludes every unnumbered -headline from the table of contents. - - -File: org.info, Node: Include Files, Next: Macro Replacement, Prev: Table of Contents, Up: Exporting - -13.4 Include Files -================== - -During export, you can include the content of another file. For -example, to include your ‘.emacs’ file, you could use: - - #+INCLUDE: "~/.emacs" src emacs-lisp - -The first parameter is the file name to include. The optional second -parameter specifies the block type: ‘example’, ‘export’ or ‘src’. The -optional third parameter specifies the source code language to use for -formatting the contents. This is relevant to both ‘export’ and ‘src’ -block types. - - If an included file is specified as having a markup language, Org -neither checks for valid syntax nor changes the contents in any way. -For example and source blocks, Org code-escapes the contents before -inclusion. - - If an included file is not specified as having any markup language, -Org assumes it be in Org format and proceeds as usual with a few -exceptions. Org makes the footnote labels (see *note Creating -Footnotes::) in the included file local to that file. The contents of -the included file belong to the same structure—headline, item—containing -the ‘INCLUDE’ keyword. In particular, headlines within the file become -children of the current section. That behavior can be changed by -providing an additional keyword parameter, ‘:minlevel’. It shifts the -headlines in the included file to become the lowest level. For example, -this syntax makes the included file a sibling of the current top-level -headline: - - #+INCLUDE: "~/my-book/chapter2.org" :minlevel 1 - - Inclusion of only portions of files are specified using ranges -parameter with ‘:lines’ keyword. The line at the upper end of the range -will not be included. The start and/or the end of the range may be -omitted to use the obvious defaults. - -‘#+INCLUDE: "~/.emacs" :lines "5-10"’ Include lines 5 to 10, 10 excluded -‘#+INCLUDE: "~/.emacs" :lines "-10"’ Include lines 1 to 10, 10 excluded -‘#+INCLUDE: "~/.emacs" :lines "10-"’ Include lines from 10 to EOF - - Inclusions may specify a file-link to extract an object matched by -‘org-link-search’(1) (see *note Search Options::). The ranges for -‘:lines’ keyword are relative to the requested element. Therefore, - - #+INCLUDE: "./paper.org::*conclusion" :lines 1-20 - -includes the first 20 lines of the headline named ‘conclusion’. - - To extract only the contents of the matched object, set -‘:only-contents’ property to non-‘nil’. This omits any planning lines -or property drawers. For example, to include the body of the heading -with the custom ID ‘theory’, you can use - - #+INCLUDE: "./paper.org::#theory" :only-contents t - - The following command allows navigating to the included document: - -‘C-c '’ (‘org-edit~special’) - - Visit the included file at point. - - ---------- Footnotes ---------- - - (1) Note that ‘org-link-search-must-match-exact-headline’ is locally -bound to non-‘nil’. Therefore, ‘org-link-search’ only matches headlines -and named elements. - - -File: org.info, Node: Macro Replacement, Next: Comment Lines, Prev: Include Files, Up: Exporting - -13.5 Macro Replacement -====================== - -Macros replace text snippets during export. Macros are defined globally -in ‘org-export-global-macros’, or document-wise with the following -syntax: - - #+MACRO: name replacement text; $1, $2 are arguments - -which can be referenced using ‘{{{name(arg1, arg2)}}}’(1). For example - - #+MACRO: poem Rose is $1, violet's $2. Life's ordered: Org assists you. - {{{poem(red,blue)}}} - -becomes - - Rose is red, violet's blue. Life's ordered: Org assists you. - - As a special case, Org parses any replacement text starting with -‘(eval’ as an Emacs Lisp expression and evaluates it accordingly. -Within such templates, arguments become strings. Thus, the following -macro - - #+MACRO: gnustamp (eval (concat "GNU/" (capitalize $1))) - -turns ‘{{{gnustamp(linux)}}}’ into ‘GNU/Linux’ during export. - - Org recognizes macro references in following Org markup areas: -paragraphs, headlines, verse blocks, tables cells and lists. Org also -recognizes macro references in keywords, such as ‘CAPTION’, ‘TITLE’, -‘AUTHOR’, ‘DATE’, and for some back-end specific export options. - - Org comes with following pre-defined macros: - -‘{{{keyword(NAME)}}}’ -‘{{{title}}}’ -‘{{{author}}}’ -‘{{{email}}}’ - The ‘keyword’ macro collects all values from NAME keywords - throughout the buffer, separated with white space. ‘title’, - ‘author’ and ‘email’ macros are shortcuts for, respectively, - ‘{{{keyword(TITLE)}}}’, ‘{{{keyword(AUTHOR)}}}’ and - ‘{{{keyword(EMAIL)}}}’. - -‘{{{date}}}’ -‘{{{date(FORMAT)}}}’ - This macro refers to the ‘DATE’ keyword. FORMAT is an optional - argument to the ‘date’ macro that is used only if ‘DATE’ is a - single timestamp. FORMAT should be a format string understood by - ‘format-time-string’. - -‘{{{time(FORMAT)}}}’ -‘{{{modification-time(FORMAT, VC)}}}’ - These macros refer to the document’s date and time of export and - date and time of modification. FORMAT is a string understood by - ‘format-time-string’. If the second argument to the - ‘modification-time’ macro is non-‘nil’, Org uses ‘vc.el’ to - retrieve the document’s modification time from the version control - system. Otherwise Org reads the file attributes. - -‘{{{input-file}}}’ - This macro refers to the filename of the exported file. - -‘{{{property(PROPERTY-NAME)}}}’ -‘{{{property(PROPERTY-NAME, SEARCH OPTION)}}}’ - This macro returns the value of property PROPERTY-NAME in the - current entry. If SEARCH-OPTION (see *note Search Options::) - refers to a remote entry, use it instead. - -‘{{{n}}}’ -‘{{{n(NAME)}}}’ -‘{{{n(NAME, ACTION)}}}’ - This macro implements custom counters by returning the number of - times the macro has been expanded so far while exporting the - buffer. You can create more than one counter using different NAME - values. If ACTION is ‘-’, previous value of the counter is held, - i.e., the specified counter is not incremented. If the value is a - number, the specified counter is set to that value. If it is any - other non-empty string, the specified counter is reset to 1. You - may leave NAME empty to reset the default counter. - - Moreover, inline source blocks (see *note Structure of Code Blocks::) -use the special ‘results’ macro to mark their output. As such, you are -advised against re-defining it, unless you know what you are doing. - - The surrounding brackets can be made invisible by setting -‘org-hide-macro-markers’ to a non-‘nil’ value. - - Org expands macros at the very beginning of the export process. - - ---------- Footnotes ---------- - - (1) Since commas separate the arguments, commas within arguments have -to be escaped with the backslash character. So only those backslash -characters before a comma need escaping with another backslash -character. - - -File: org.info, Node: Comment Lines, Next: ASCII/Latin-1/UTF-8 export, Prev: Macro Replacement, Up: Exporting - -13.6 Comment Lines -================== - -Lines starting with zero or more whitespace characters followed by one -‘#’ and a whitespace are treated as comments and, as such, are not -exported. - - Likewise, regions surrounded by ‘#+BEGIN_COMMENT’ ... ‘#+END_COMMENT’ -are not exported. - - Finally, a ‘COMMENT’ keyword at the beginning of an entry, but after -any other keyword or priority cookie, comments out the entire subtree. -In this case, the subtree is not exported and no code block within it is -executed either(1). The command below helps changing the comment status -of a headline. - -‘C-c ;’ (‘org-toggle-comment’) - - Toggle the ‘COMMENT’ keyword at the beginning of an entry. - - ---------- Footnotes ---------- - - (1) For a less drastic behavior, consider using a select tag (see -*note Export Settings::) instead. - - -File: org.info, Node: ASCII/Latin-1/UTF-8 export, Next: Beamer Export, Prev: Comment Lines, Up: Exporting - -13.7 ASCII/Latin-1/UTF-8 export -=============================== - -ASCII export produces an output file containing only plain ASCII -characters. This is the simplest and most direct text output. It does -not contain any Org markup. Latin-1 and UTF-8 export use additional -characters and symbols available in these encoding standards. All three -of these export formats offer the most basic of text output for maximum -portability. - - On export, Org fills and justifies text according to the text width -set in ‘org-ascii-text-width’. - - Org exports links using a footnote-like style where the descriptive -part is in the text and the link is in a note before the next heading. -See the variable ‘org-ascii-links-to-notes’ for details. - -ASCII export commands ---------------------- - -‘C-c C-e t a’ (‘org-ascii-export-to-ascii’) -‘C-c C-e t l’ -‘C-c C-e t u’ - - Export as an ASCII file with a ‘.txt’ extension. For ‘myfile.org’, - Org exports to ‘myfile.txt’, overwriting without warning. For - ‘myfile.txt’, Org exports to ‘myfile.txt.txt’ in order to prevent - data loss. - -‘C-c C-e t A’ (‘org-ascii-export-to-ascii’) -‘C-c C-e t L’ -‘C-c C-e t U’ - - Export to a temporary buffer. Does not create a file. - -ASCII specific export settings ------------------------------- - -The ASCII export back-end has one extra keyword for customizing ASCII -output. Setting this keyword works similar to the general options (see -*note Export Settings::). - -‘SUBTITLE’ - The document subtitle. For long subtitles, use multiple - ‘#+SUBTITLE’ lines in the Org file. Org prints them on one - continuous line, wrapping into multiple lines if necessary. - -Header and sectioning structure -------------------------------- - -Org converts the first three outline levels into headlines for ASCII -export. The remaining levels are turned into lists. To change this -cut-off point where levels become lists, see *note Export Settings::. - -Quoting ASCII text ------------------- - -To insert text within the Org file by the ASCII back-end, use one the -following constructs, inline, keyword, or export block: - - Inline text @@ascii:and additional text@@ within a paragraph. - - #+ASCII: Some text - - #+BEGIN_EXPORT ascii - Org exports text in this block only when using ASCII back-end. - #+END_EXPORT - -ASCII specific attributes -------------------------- - -ASCII back-end recognizes only one attribute, ‘:width’, which specifies -the width of a horizontal rule in number of characters. The keyword and -syntax for specifying widths is: - - #+ATTR_ASCII: :width 10 - ----- - -ASCII special blocks --------------------- - -Besides ‘#+BEGIN_CENTER’ blocks (see *note Paragraphs::), ASCII back-end -has these two left and right justification blocks: - - #+BEGIN_JUSTIFYLEFT - It's just a jump to the left... - #+END_JUSTIFYLEFT - - #+BEGIN_JUSTIFYRIGHT - ...and then a step to the right. - #+END_JUSTIFYRIGHT - - -File: org.info, Node: Beamer Export, Next: HTML Export, Prev: ASCII/Latin-1/UTF-8 export, Up: Exporting - -13.8 Beamer Export -================== - -Org uses Beamer export to convert an Org file tree structure into -high-quality interactive slides for presentations. Beamer is a LaTeX -document class for creating presentations in PDF, HTML, and other -popular display formats. - -* Menu: - -* Beamer export commands:: For creating Beamer documents. -* Beamer specific export settings:: For customizing Beamer export. -* Frames and Blocks in Beamer:: For composing Beamer slides. -* Beamer specific syntax:: For using in Org documents. -* Editing support:: Editing support. -* A Beamer example:: A complete presentation. - - -File: org.info, Node: Beamer export commands, Next: Beamer specific export settings, Up: Beamer Export - -13.8.1 Beamer export commands ------------------------------ - -‘C-c C-e l b’ (‘org-beamer-export-to-latex’) - - Export as LaTeX file with a ‘.tex’ extension. For ‘myfile.org’, - Org exports to ‘myfile.tex’, overwriting without warning. - -‘C-c C-e l B’ (‘org-beamer-export-as-latex’) - - Export to a temporary buffer. Does not create a file. - -‘C-c C-e l P’ (‘org-beamer-export-to-pdf’) - - Export as LaTeX file and then convert it to PDF format. - -‘C-c C-e l O’ - - Export as LaTeX file, convert it to PDF format, and then open the - PDF file. - - -File: org.info, Node: Beamer specific export settings, Next: Frames and Blocks in Beamer, Prev: Beamer export commands, Up: Beamer Export - -13.8.2 Beamer specific export settings --------------------------------------- - -Beamer export back-end has several additional keywords for customizing -Beamer output. These keywords work similar to the general options -settings (see *note Export Settings::). - -‘BEAMER_THEME’ - The Beamer layout theme (‘org-beamer-theme’). Use square brackets - for options. For example: - - #+BEAMER_THEME: Rochester [height=20pt] - -‘BEAMER_FONT_THEME’ - The Beamer font theme. - -‘BEAMER_INNER_THEME’ - The Beamer inner theme. - -‘BEAMER_OUTER_THEME’ - The Beamer outer theme. - -‘BEAMER_HEADER’ - Arbitrary lines inserted in the preamble, just before the - ‘hyperref’ settings. - -‘DESCRIPTION’ - The document description. For long descriptions, use multiple - ‘DESCRIPTION’ keywords. By default, ‘hyperref’ inserts - ‘DESCRIPTION’ as metadata. Use ‘org-latex-hyperref-template’ to - configure document metadata. Use ‘org-latex-title-command’ to - configure typesetting of description as part of front matter. - -‘KEYWORDS’ - The keywords for defining the contents of the document. Use - multiple ‘KEYWORDS’ lines if necessary. By default, ‘hyperref’ - inserts ‘KEYWORDS’ as metadata. Use ‘org-latex-hyperref-template’ - to configure document metadata. Use ‘org-latex-title-command’ to - configure typesetting of keywords as part of front matter. - -‘SUBTITLE’ - Document’s subtitle. For typesetting, use - ‘org-beamer-subtitle-format’ string. Use - ‘org-latex-hyperref-template’ to configure document metadata. Use - ‘org-latex-title-command’ to configure typesetting of subtitle as - part of front matter. - - -File: org.info, Node: Frames and Blocks in Beamer, Next: Beamer specific syntax, Prev: Beamer specific export settings, Up: Beamer Export - -13.8.3 Frames and Blocks in Beamer ----------------------------------- - -Org transforms heading levels into Beamer’s sectioning elements, frames -and blocks. Any Org tree with a not-too-deep-level nesting should in -principle be exportable as a Beamer presentation. - - • Org headlines become Beamer frames when the heading level in Org is - equal to ‘org-beamer-frame-level’ or ‘H’ value in a ‘OPTIONS’ line - (see *note Export Settings::). - - Org overrides headlines to frames conversion for the current tree - of an Org file if it encounters the ‘BEAMER_ENV’ property set to - ‘frame’ or ‘fullframe’. Org ignores whatever - ‘org-beamer-frame-level’ happens to be for that headline level in - the Org tree. In Beamer terminology, a full frame is a frame - without its title. - - • Org exports a Beamer frame’s objects as block environments. Org - can enforce wrapping in special block types when ‘BEAMER_ENV’ - property is set(1). For valid values see - ‘org-beamer-environments-default’. To add more values, see - ‘org-beamer-environments-extra’. - - • If ‘BEAMER_ENV’ is set to ‘appendix’, Org exports the entry as an - appendix. When set to ‘note’, Org exports the entry as a note - within the frame or between frames, depending on the entry’s - heading level. When set to ‘noteNH’, Org exports the entry as a - note without its title. When set to ‘againframe’, Org exports the - entry with ‘\againframe’ command, which makes setting the - ‘BEAMER_REF’ property mandatory because ‘\againframe’ needs frame - to resume. - - When ‘ignoreheading’ is set, Org export ignores the entry’s - headline but not its content. This is useful for inserting content - between frames. It is also useful for properly closing a ‘column’ - environment. @end itemize - - When ‘BEAMER_ACT’ is set for a headline, Org export translates that - headline as an overlay or action specification. When enclosed in - square brackets, Org export makes the overlay specification a - default. Use ‘BEAMER_OPT’ to set any options applicable to the - current Beamer frame or block. The Beamer export back-end wraps - with appropriate angular or square brackets. It also adds the - ‘fragile’ option for any code that may require a verbatim block. - - To create a column on the Beamer slide, use the ‘BEAMER_COL’ - property for its headline in the Org file. Set the value of - ‘BEAMER_COL’ to a decimal number representing the fraction of the - total text width. Beamer export uses this value to set the - column’s width and fills the column with the contents of the Org - entry. If the Org entry has no specific environment defined, - Beamer export ignores the heading. If the Org entry has a defined - environment, Beamer export uses the heading as title. Behind the - scenes, Beamer export automatically handles LaTeX column - separations for contiguous headlines. To manually adjust them for - any unique configurations needs, use the ‘BEAMER_ENV’ property. - - ---------- Footnotes ---------- - - (1) If ‘BEAMER_ENV’ is set, Org export adds ‘B_environment’ tag to -make it visible. The tag serves as a visual aid and has no semantic -relevance. - - -File: org.info, Node: Beamer specific syntax, Next: Editing support, Prev: Frames and Blocks in Beamer, Up: Beamer Export - -13.8.4 Beamer specific syntax ------------------------------ - -Since Org’s Beamer export back-end is an extension of the LaTeX -back-end, it recognizes other LaTeX specific syntax—for example, -‘#+LATEX:’ or ‘#+ATTR_LATEX:’. See *note LaTeX Export::, for details. - - Beamer export wraps the table of contents generated with ‘toc:t’ -‘OPTION’ keyword in a ‘frame’ environment. Beamer export does not wrap -the table of contents generated with ‘TOC’ keyword (see *note Table of -Contents::). Use square brackets for specifying options. - - #+TOC: headlines [currentsection] - - Insert Beamer-specific code using the following constructs: - - #+BEAMER: \pause - - #+BEGIN_EXPORT beamer - Only Beamer export back-end exports this. - #+END_BEAMER - - Text @@beamer:some code@@ within a paragraph. - - Inline constructs, such as the last one above, are useful for adding -overlay specifications to objects with ‘bold’, ‘item’, ‘link’, -‘radio-target’ and ‘target’ types. Enclose the value in angular -brackets and place the specification at the beginning of the object as -shown in this example: - - A *@@beamer:<2->@@useful* feature - - Beamer export recognizes the ‘ATTR_BEAMER’ keyword with the following -attributes from Beamer configurations: ‘:environment’ for changing local -Beamer environment, ‘:overlay’ for specifying Beamer overlays in angular -or square brackets, and ‘:options’ for inserting optional arguments. - - #+ATTR_BEAMER: :environment nonindentlist - - item 1, not indented - - item 2, not indented - - item 3, not indented - - #+ATTR_BEAMER: :overlay <+-> - - item 1 - - item 2 - - #+ATTR_BEAMER: :options [Lagrange] - Let $G$ be a finite group, and let $H$ be - a subgroup of $G$. Then the order of $H$ divides the order of $G$. - - -File: org.info, Node: Editing support, Next: A Beamer example, Prev: Beamer specific syntax, Up: Beamer Export - -13.8.5 Editing support ----------------------- - -Org Beamer mode is a special minor mode for faster editing of Beamer -documents. - - #+STARTUP: beamer - -‘C-c C-b’ (‘org-beamer-select-environment’) - - Org Beamer mode provides this key for quicker selections in Beamer - normal environments, and for selecting the ‘BEAMER_COL’ property. - - -File: org.info, Node: A Beamer example, Prev: Editing support, Up: Beamer Export - -13.8.6 A Beamer example ------------------------ - -Here is an example of an Org document ready for Beamer export. - - #+TITLE: Example Presentation - #+AUTHOR: Carsten Dominik - #+OPTIONS: H:2 toc:t num:t - #+LATEX_CLASS: beamer - #+LATEX_CLASS_OPTIONS: [presentation] - #+BEAMER_THEME: Madrid - #+COLUMNS: %45ITEM %10BEAMER_ENV(Env) %10BEAMER_ACT(Act) %4BEAMER_COL(Col) - - * This is the first structural section - - ** Frame 1 - *** Thanks to Eric Fraga :B_block: - :PROPERTIES: - :BEAMER_COL: 0.48 - :BEAMER_ENV: block - :END: - for the first viable Beamer setup in Org - *** Thanks to everyone else :B_block: - :PROPERTIES: - :BEAMER_COL: 0.48 - :BEAMER_ACT: <2-> - :BEAMER_ENV: block - :END: - for contributing to the discussion - **** This will be formatted as a beamer note :B_note: - :PROPERTIES: - :BEAMER_env: note - :END: - ** Frame 2 (where we will not use columns) - *** Request - Please test this stuff! - - -File: org.info, Node: HTML Export, Next: LaTeX Export, Prev: Beamer Export, Up: Exporting - -13.9 HTML Export -================ - -Org mode contains an HTML exporter with extensive HTML formatting -compatible with XHTML 1.0 strict standard. - -* Menu: - -* HTML export commands:: Invoking HTML export. -* HTML specific export settings:: Settings for HTML export. -* HTML doctypes:: Exporting various (X)HTML flavors. -* HTML preamble and postamble:: Inserting preamble and postamble. -* Quoting HTML tags:: Using direct HTML in Org files. -* Headlines in HTML export:: Formatting headlines. -* Links in HTML export:: Inserting and formatting links. -* Tables in HTML export:: How to modify the formatting of tables. -* Images in HTML export:: How to insert figures into HTML output. -* Math formatting in HTML export:: Beautiful math also on the web. -* Text areas in HTML export:: An alternate way to show an example. -* CSS support:: Changing the appearance of the output. -* JavaScript support:: Info and folding in a web browser. - - -File: org.info, Node: HTML export commands, Next: HTML specific export settings, Up: HTML Export - -13.9.1 HTML export commands ---------------------------- - -‘C-c C-e h h’ (‘org-html-export-to-html’) - - Export as HTML file with a ‘.html’ extension. For ‘myfile.org’, - Org exports to ‘myfile.html’, overwriting without warning. ‘C-c - C-e h o’ exports to HTML and opens it in a web browser. - -‘C-c C-e h H’ (‘org-html-export-as-html’) - - Exports to a temporary buffer. Does not create a file. - - -File: org.info, Node: HTML specific export settings, Next: HTML doctypes, Prev: HTML export commands, Up: HTML Export - -13.9.2 HTML specific export settings ------------------------------------- - -HTML export has a number of keywords, similar to the general options -settings described in *note Export Settings::. - -‘DESCRIPTION’ - This is the document’s description, which the HTML exporter inserts - it as a HTML meta tag in the HTML file. For long descriptions, use - multiple ‘DESCRIPTION’ lines. The exporter takes care of wrapping - the lines properly. - - The exporter includes a number of other meta tags, which can be - customized by modifying ‘org-html-meta-tags’. - -‘HTML_DOCTYPE’ - Specify the document type, for example: HTML5 (‘org-html-doctype’). - -‘HTML_CONTAINER’ - Specify the HTML container, such as ‘div’, for wrapping sections - and elements (‘org-html-container-element’). - -‘HTML_LINK_HOME’ - The URL for home link (‘org-html-link-home’). - -‘HTML_LINK_UP’ - The URL for the up link of exported HTML pages - (‘org-html-link-up’). - -‘HTML_MATHJAX’ - Options for MathJax (‘org-html-mathjax-options’). MathJax is used - to typeset LaTeX math in HTML documents. See *note Math formatting - in HTML export::, for an example. - -‘HTML_HEAD’ - Arbitrary lines for appending to the HTML document’s head - (‘org-html-head’). - -‘HTML_HEAD_EXTRA’ - More arbitrary lines for appending to the HTML document’s head - (‘org-html-head-extra’). - -‘KEYWORDS’ - Keywords to describe the document’s content. HTML exporter inserts - these keywords as HTML meta tags. For long keywords, use multiple - ‘KEYWORDS’ lines. - -‘LATEX_HEADER’ - Arbitrary lines for appending to the preamble; HTML exporter - appends when transcoding LaTeX fragments to images (see *note Math - formatting in HTML export::). - -‘SUBTITLE’ - The document’s subtitle. HTML exporter formats subtitle if - document type is ‘HTML5’ and the CSS has a ‘subtitle’ class. - - Some of these keywords are explained in more detail in the following -sections of the manual. - - -File: org.info, Node: HTML doctypes, Next: HTML preamble and postamble, Prev: HTML specific export settings, Up: HTML Export - -13.9.3 HTML doctypes --------------------- - -Org can export to various (X)HTML flavors. - - Set the ‘org-html-doctype’ variable for different (X)HTML variants. -Depending on the variant, the HTML exporter adjusts the syntax of HTML -conversion accordingly. Org includes the following ready-made variants: - - • ‘"html4-strict"’ - • ‘"html4-transitional"’ - • ‘"html4-frameset"’ - • ‘"xhtml-strict"’ - • ‘"xhtml-transitional"’ - • ‘"xhtml-frameset"’ - • ‘"xhtml-11"’ - • ‘"html5"’ - • ‘"xhtml5"’ - -See the variable ‘org-html-doctype-alist’ for details. The default is -‘"xhtml-strict"’. - - Org’s HTML exporter does not by default enable new block elements -introduced with the HTML5 standard. To enable them, set -‘org-html-html5-fancy’ to non-‘nil’. Or use an ‘OPTIONS’ line in the -file to set ‘html5-fancy’. - - HTML5 documents can now have arbitrary ‘#+BEGIN’ ... ‘#+END’ blocks. -For example: - - #+BEGIN_aside - Lorem ipsum - #+END_aside - -exports to: - - <aside> - <p>Lorem ipsum</p> - </aside> - -while this: - - #+ATTR_HTML: :controls controls :width 350 - #+BEGIN_video - #+HTML: <source src="movie.mp4" type="video/mp4"> - #+HTML: <source src="movie.ogg" type="video/ogg"> - Your browser does not support the video tag. - #+END_video - -exports to: - - <video controls="controls" width="350"> - <source src="movie.mp4" type="video/mp4"> - <source src="movie.ogg" type="video/ogg"> - <p>Your browser does not support the video tag.</p> - </video> - - When special blocks do not have a corresponding HTML5 element, the -HTML exporter reverts to standard translation (see -‘org-html-html5-elements’). For example, ‘#+BEGIN_lederhosen’ exports -to ‘<div class="lederhosen">’. - - Special blocks cannot have headlines. For the HTML exporter to wrap -the headline and its contents in ‘<section>’ or ‘<article>’ tags, set -the ‘HTML_CONTAINER’ property for the headline. - - -File: org.info, Node: HTML preamble and postamble, Next: Quoting HTML tags, Prev: HTML doctypes, Up: HTML Export - -13.9.4 HTML preamble and postamble ----------------------------------- - -The HTML exporter has delineations for preamble and postamble. The -default value for ‘org-html-preamble’ is ‘t’, which makes the HTML -exporter insert the preamble. See the variable -‘org-html-preamble-format’ for the format string. - - Set ‘org-html-preamble’ to a string to override the default format -string. If the string is a function, the HTML exporter expects the -function to return a string upon execution. The HTML exporter inserts -this string in the preamble. The HTML exporter does not insert a -preamble if ‘org-html-preamble’ is set ‘nil’. - - The default value for ‘org-html-postamble’ is ‘auto’, which makes the -HTML exporter build a postamble from looking up author’s name, email -address, creator’s name, and date. Set ‘org-html-postamble’ to ‘t’ to -insert the postamble in the format specified in the -‘org-html-postamble-format’ variable. The HTML exporter does not insert -a postamble if ‘org-html-postamble’ is set to ‘nil’. - - -File: org.info, Node: Quoting HTML tags, Next: Headlines in HTML export, Prev: HTML preamble and postamble, Up: HTML Export - -13.9.5 Quoting HTML tags ------------------------- - -The HTML export back-end transforms ‘<’ and ‘>’ to ‘<’ and ‘>’. -To include raw HTML code in the Org file so the HTML export back-end can -insert that HTML code in the output, use this inline syntax: -‘@@html:...@@’. For example: - - @@html:<b>@@bold text@@html:</b>@@ - - For larger raw HTML code blocks, use these HTML export code blocks: - - #+HTML: Literal HTML code for export - - #+BEGIN_EXPORT html - All lines between these markers are exported literally - #+END_EXPORT - - -File: org.info, Node: Headlines in HTML export, Next: Links in HTML export, Prev: Quoting HTML tags, Up: HTML Export - -13.9.6 Headlines in HTML export -------------------------------- - -Headlines are exported to ‘<h1>’, ‘<h2>’, etc. Each headline gets the -‘id’ attribute from ‘CUSTOM_ID’ property, or a unique generated value, -see *note Internal Links::. - - When ‘org-html-self-link-headlines’ is set to a non-‘nil’ value, the -text of the headlines is also wrapped in ‘<a>’ tags. These tags have a -‘href’ attribute making the headlines link to themselves. - - -File: org.info, Node: Links in HTML export, Next: Tables in HTML export, Prev: Headlines in HTML export, Up: HTML Export - -13.9.7 Links in HTML export ---------------------------- - -The HTML export back-end transforms Org’s internal links (see *note -Internal Links::) to equivalent HTML links in the output. The back-end -similarly handles Org’s automatic links created by radio targets (see -*note Radio Targets::) similarly. For Org links to external files, the -back-end transforms the links to _relative_ paths. - - For Org links to other ‘.org’ files, the back-end automatically -changes the file extension to ‘.html’ and makes file paths relative. If -the ‘.org’ files have an equivalent ‘.html’ version at the same -location, then the converted links should work without any further -manual intervention. However, to disable this automatic path -translation, set ‘org-html-link-org-files-as-html’ to ‘nil’. When -disabled, the HTML export back-end substitutes the ID-based links in the -HTML output. For more about linking files when publishing to a -directory, see *note Publishing links::. - - Org files can also have special directives to the HTML export -back-end. For example, by using ‘#+ATTR_HTML’ lines to specify new -format attributes to ‘<a>’ or ‘<img>’ tags. This example shows changing -the link’s title and style: - - #+ATTR_HTML: :title The Org mode homepage :style color:red; - [[https://orgmode.org]] - - -File: org.info, Node: Tables in HTML export, Next: Images in HTML export, Prev: Links in HTML export, Up: HTML Export - -13.9.8 Tables in HTML export ----------------------------- - -The HTML export back-end uses ‘org-html-table-default-attributes’ when -exporting Org tables to HTML. By default, the exporter does not draw -frames and cell borders. To change for this for a table, use the -following lines before the table in the Org file: - - #+CAPTION: This is a table with lines around and between cells - #+ATTR_HTML: :border 2 :rules all :frame border - - The HTML export back-end preserves column groupings in Org tables -(see *note Column Groups::) when exporting to HTML. - - Additional options for customizing tables for HTML export. - -‘org-html-table-align-individual-fields’ - Non-‘nil’ attaches style attributes for alignment to each table - field. - -‘org-html-table-caption-above’ - Non-‘nil’ places caption string at the beginning of the table. - -‘org-html-table-data-tags’ - Opening and ending tags for table data fields. - -‘org-html-table-default-attributes’ - Default attributes and values for table tags. - -‘org-html-table-header-tags’ - Opening and ending tags for table’s header fields. - -‘org-html-table-row-tags’ - Opening and ending tags for table rows. - -‘org-html-table-use-header-tags-for-first-column’ - Non-‘nil’ formats column one in tables with header tags. - - -File: org.info, Node: Images in HTML export, Next: Math formatting in HTML export, Prev: Tables in HTML export, Up: HTML Export - -13.9.9 Images in HTML export ----------------------------- - -The HTML export back-end has features to convert Org image links to HTML -inline images and HTML clickable image links. - - When the link in the Org file has no description, the HTML export -back-end by default in-lines that image. For example: -‘[[file:myimg.jpg]]’ is in-lined, while ‘[[file:myimg.jpg][the image]]’ -links to the text, ‘the image’. For more details, see the variable -‘org-html-inline-images’. - - On the other hand, if the description part of the Org link is itself -another link, such as ‘file:’ or ‘http:’ URL pointing to an image, the -HTML export back-end in-lines this image and links to the main image. -This Org syntax enables the back-end to link low-resolution thumbnail to -the high-resolution version of the image, as shown in this example: - - [[file:highres.jpg][file:thumb.jpg]] - - To change attributes of in-lined images, use ‘#+ATTR_HTML’ lines in -the Org file. This example shows realignment to right, and adds ‘alt’ -and ‘title’ attributes in support of text viewers and modern web -accessibility standards. - - #+CAPTION: A black cat stalking a spider - #+ATTR_HTML: :alt cat/spider image :title Action! :align right - [[./img/a.jpg]] - - The HTML export back-end copies the ‘http’ links from the Org file -as-is. - - -File: org.info, Node: Math formatting in HTML export, Next: Text areas in HTML export, Prev: Images in HTML export, Up: HTML Export - -13.9.10 Math formatting in HTML export --------------------------------------- - -LaTeX math snippets (see *note LaTeX fragments::) can be displayed in -two different ways on HTML pages. The default is to use the MathJax -(https://www.mathjax.org), which should work out of the box with -Org(1)(2). Some MathJax display options can be configured via -‘org-html-mathjax-options’, or in the buffer. For example, with the -following settings, - - #+HTML_MATHJAX: align: left indent: 5em tagside: left font: Neo-Euler - #+HTML_MATHJAX: cancel.js noErrors.js - -equation labels are displayed on the left margin and equations are five -em from the left margin. In addition, it loads the two MathJax -extensions ‘cancel.js’ and ‘noErrors.js’(3). - - See the docstring of ‘org-html-mathjax-options’ for all supported -variables. The MathJax template can be configure via -‘org-html-mathjax-template’. - - If you prefer, you can also request that LaTeX fragments are -processed into small images that will be inserted into the browser page. -Before the availability of MathJax, this was the default method for Org -files. This method requires that the dvipng program, dvisvgm or -ImageMagick suite is available on your system. You can still get this -processing with - - #+OPTIONS: tex:dvipng - - #+OPTIONS: tex:dvisvgm - -or - - #+OPTIONS: tex:imagemagick - - ---------- Footnotes ---------- - - (1) By default Org loads MathJax from cdnjs.com (https://cdnjs.com) -as recommended by MathJax (https://www.mathjax.org). - - (2) Please note that exported formulas are part of an HTML document, -and that signs such as ‘<’, ‘>’, or ‘&’ have special meanings. See -MathJax TeX and LaTeX support -(http://docs.mathjax.org/en/latest/tex.html#tex-and-latex-in-html-documents). - - (3) See TeX and LaTeX extensions -(http://docs.mathjax.org/en/latest/tex.html#tex-extensions) in the -MathJax manual (http://docs.mathjax.org) to learn about extensions. - - -File: org.info, Node: Text areas in HTML export, Next: CSS support, Prev: Math formatting in HTML export, Up: HTML Export - -13.9.11 Text areas in HTML export ---------------------------------- - -Before Org mode’s Babel, one popular approach to publishing code in HTML -was by using ‘:textarea’. The advantage of this approach was that -copying and pasting was built into browsers with simple JavaScript -commands. Even editing before pasting was made simple. - - The HTML export back-end can create such text areas. It requires an -‘#+ATTR_HTML’ line as shown in the example below with the ‘:textarea’ -option. This must be followed by either an example or a source code -block. Other Org block types do not honor the ‘:textarea’ option. - - By default, the HTML export back-end creates a text area 80 -characters wide and height just enough to fit the content. Override -these defaults with ‘:width’ and ‘:height’ options on the ‘#+ATTR_HTML’ -line. - - #+ATTR_HTML: :textarea t :width 40 - #+BEGIN_EXAMPLE - (defun org-xor (a b) - "Exclusive or." - (if a (not b) b)) - #+END_EXAMPLE - - -File: org.info, Node: CSS support, Next: JavaScript support, Prev: Text areas in HTML export, Up: HTML Export - -13.9.12 CSS support -------------------- - -You can modify the CSS style definitions for the exported file. The -HTML exporter assigns the following special CSS classes(1) to -appropriate parts of the document—your style specifications may change -these, in addition to any of the standard classes like for headlines, -tables, etc. - -‘p.author’ author information, including email -‘p.date’ publishing date -‘p.creator’ creator info, about org mode version -‘.title’ document title -‘.subtitle’ document subtitle -‘.todo’ TODO keywords, all not-done states -‘.done’ the DONE keywords, all states that count as done -‘.WAITING’ each TODO keyword also uses a class named after itself -‘.timestamp’ timestamp -‘.timestamp-kwd’ keyword associated with a timestamp, like ‘SCHEDULED’ -‘.timestamp-wrapper’ span around keyword plus timestamp -‘.tag’ tag in a headline -‘._HOME’ each tag uses itself as a class, “@” replaced by “_” -‘.target’ target for links -‘.linenr’ the line number in a code example -‘.code-highlighted’ for highlighting referenced code lines -‘div.outline-N’ div for outline level N (headline plus text) -‘div.outline-text-N’ extra div for text at outline level N -‘.section-number-N’ section number in headlines, different for each level -‘.figure-number’ label like “Figure 1:” -‘.table-number’ label like “Table 1:” -‘.listing-number’ label like “Listing 1:” -‘div.figure’ how to format an in-lined image -‘pre.src’ formatted source code -‘pre.example’ normal example -‘p.verse’ verse paragraph -‘div.footnotes’ footnote section headline -‘p.footnote’ footnote definition paragraph, containing a footnote -‘.footref’ a footnote reference number (always a <sup>) -‘.footnum’ footnote number in footnote definition (always <sup>) -‘.org-svg’ default class for a linked ‘.svg’ image - - The HTML export back-end includes a compact default style in each -exported HTML file. To override the default style with another style, -use these keywords in the Org file. They will replace the global -defaults the HTML exporter uses. - - #+HTML_HEAD: <link rel="stylesheet" type="text/css" href="style1.css" /> - #+HTML_HEAD_EXTRA: <link rel="alternate stylesheet" type="text/css" href="style2.css" /> - - To just turn off the default style, customize -‘org-html-head-include-default-style’ variable, or use this option line -in the Org file. - - #+OPTIONS: html-style:nil - - For longer style definitions, either use several ‘HTML_HEAD’ and -‘HTML_HEAD_EXTRA’ keywords, or use ‘<style> ... </style>’ blocks around -them. Both of these approaches can avoid referring to an external file. - - In order to add styles to a sub-tree, use the ‘HTML_CONTAINER_CLASS’ -property to assign a class to the tree. In order to specify CSS styles -for a particular headline, you can use the ID specified in a ‘CUSTOM_ID’ -property. You can also assign a specific class to a headline with the -‘HTML_HEADLINE_CLASS’ property. - - Never change the ‘org-html-style-default’ constant. Instead use -other simpler ways of customizing as described above. - - ---------- Footnotes ---------- - - (1) If the classes on TODO keywords and tags lead to conflicts, use -the variables ‘org-html-todo-kwd-class-prefix’ and -‘org-html-tag-class-prefix’ to make them unique. - - -File: org.info, Node: JavaScript support, Prev: CSS support, Up: HTML Export - -13.9.13 JavaScript supported display of web pages -------------------------------------------------- - -Sebastian Rose has written a JavaScript program especially designed to -allow two different ways of viewing HTML files created with Org. One is -an _Info_-like mode where each section is displayed separately and -navigation can be done with the ‘n’ and ‘p’ keys, and some other keys as -well, press ‘?’ for an overview of the available keys. The second one -has a _folding_ view, much like Org provides inside Emacs. The script -is available at <https://orgmode.org/org-info.js> and the documentation -at <https://orgmode.org/worg/code/org-info-js/>. The script is hosted -on <https://orgmode.org>, but for reliability, prefer installing it on -your own web server. - - To use this program, just add this line to the Org file: - - #+INFOJS_OPT: view:info toc:nil - -The HTML header now has the code needed to automatically invoke the -script. For setting options, use the syntax from the above line for -options described below: - -‘path:’ - The path to the script. The default is to grab the script from - <https://orgmode.org/org-info.js>, but you might want to have a - local copy and use a path like ‘../scripts/org-info.js’. - -‘view:’ - Initial view when the website is first shown. Possible values are: - - ‘info’ Info-like interface with one section per page - ‘overview’ Folding interface, initially showing only top-level - ‘content’ Folding interface, starting with all headlines visible - ‘showall’ Folding interface, all headlines and text visible - -‘sdepth:’ - Maximum headline level still considered as an independent section - for info and folding modes. The default is taken from - ‘org-export-headline-levels’, i.e., the ‘H’ switch in ‘OPTIONS’. - If this is smaller than in ‘org-export-headline-levels’, each - info/folding section can still contain child headlines. - -‘toc:’ - Should the table of contents _initially_ be visible? Even when - ‘nil’, you can always get to the “toc” with ‘i’. - -‘tdepth:’ - The depth of the table of contents. The defaults are taken from - the variables ‘org-export-headline-levels’ and - ‘org-export-with-toc’. - -‘ftoc:’ - Does the CSS of the page specify a fixed position for the “toc”? - If yes, the toc is displayed as a section. - -‘ltoc:’ - Should there be short contents (children) in each section? Make - this ‘above’ if the section should be above initial text. - -‘mouse:’ - Headings are highlighted when the mouse is over them. Should be - ‘underline’ (default) or a background color like ‘#cccccc’. - -‘buttons:’ - Should view-toggle buttons be everywhere? When ‘nil’ (the - default), only one such button is present. - - You can choose default values for these options by customizing the -variable ‘org-infojs-options’. If you always want to apply the script -to your pages, configure the variable ‘org-export-html-use-infojs’. - - -File: org.info, Node: LaTeX Export, Next: Markdown Export, Prev: HTML Export, Up: Exporting - -13.10 LaTeX Export -================== - -The LaTeX export back-end can handle complex documents, incorporate -standard or custom LaTeX document classes, generate documents using -alternate LaTeX engines, and produce fully linked PDF files with -indexes, bibliographies, and tables of contents, destined for -interactive online viewing or high-quality print publication. - - While the details are covered in-depth in this section, here are some -quick references to variables for the impatient: for engines, see -‘org-latex-compiler’; for build sequences, see ‘org-latex-pdf-process’; -for packages, see ‘org-latex-default-packages-alist’ and -‘org-latex-packages-alist’. - - An important note about the LaTeX export back-end: it is sensitive to -blank lines in the Org document. That’s because LaTeX itself depends on -blank lines to tell apart syntactical elements, such as paragraphs. - -* Menu: - -* LaTeX/PDF export commands:: For producing LaTeX and PDF documents. -* LaTeX specific export settings:: Unique to this LaTeX back-end. -* LaTeX header and sectioning:: Setting up the export file structure. -* Quoting LaTeX code:: Incorporating literal LaTeX code. -* Tables in LaTeX export:: Options for exporting tables to LaTeX. -* Images in LaTeX export:: How to insert figures into LaTeX output. -* Plain lists in LaTeX export:: Attributes specific to lists. -* Source blocks in LaTeX export:: Attributes specific to source code blocks. -* Example blocks in LaTeX export:: Attributes specific to example blocks. -* Special blocks in LaTeX export:: Attributes specific to special blocks. -* Horizontal rules in LaTeX export:: Attributes specific to horizontal rules. -* Verse blocks in LaTeX export:: Attributes specific to special blocks. -* Quote blocks in LaTeX export:: Attributes specific to quote blocks. - - -File: org.info, Node: LaTeX/PDF export commands, Next: LaTeX specific export settings, Up: LaTeX Export - -13.10.1 LaTeX/PDF export commands ---------------------------------- - -‘C-c C-e l l’ (‘org-latex-export-to-latex’) - Export to a LaTeX file with a ‘.tex’ extension. For ‘myfile.org’, - Org exports to ‘myfile.tex’, overwriting without warning. - -‘C-c C-e l L’ (‘org-latex-export-as-latex’) - Export to a temporary buffer. Do not create a file. - -‘C-c C-e l p’ (‘org-latex-export-to-pdf’) - Export as LaTeX file and convert it to PDF file. - -‘C-c C-e l o’ - Export as LaTeX file and convert it to PDF, then open the PDF using - the default viewer. - -‘M-x org-export-region-as-latex’ - Convert the region to LaTeX under the assumption that it was in Org - mode syntax before. This is a global command that can be invoked - in any buffer. - - The LaTeX export back-end can use any of these LaTeX engines: -‘pdflatex’, ‘xelatex’, and ‘lualatex’. These engines compile LaTeX -files with different compilers, packages, and output options. The LaTeX -export back-end finds the compiler version to use from -‘org-latex-compiler’ variable or the ‘#+LATEX_COMPILER’ keyword in the -Org file. See the docstring for the ‘org-latex-default-packages-alist’ -for loading packages with certain compilers. Also see -‘org-latex-bibtex-compiler’ to set the bibliography compiler(1). - - ---------- Footnotes ---------- - - (1) This does not allow setting different bibliography compilers for -different files. However, “smart” LaTeX compilation systems, such as -latexmk, can select the correct bibliography compiler. - - -File: org.info, Node: LaTeX specific export settings, Next: LaTeX header and sectioning, Prev: LaTeX/PDF export commands, Up: LaTeX Export - -13.10.2 LaTeX specific export settings --------------------------------------- - -The LaTeX export back-end has several additional keywords for -customizing LaTeX output. Setting these keywords works similar to the -general options (see *note Export Settings::). - -‘DESCRIPTION’ - The document’s description. The description along with author - name, keywords, and related file metadata are inserted in the - output file by the hyperref package. See - ‘org-latex-hyperref-template’ for customizing metadata items. See - ‘org-latex-title-command’ for typesetting description into the - document’s front matter. Use multiple ‘DESCRIPTION’ keywords for - long descriptions. - -‘LANGUAGE’ - In order to be effective, the ‘babel’ or ‘polyglossia’ - packages—according to the LaTeX compiler used—must be loaded with - the appropriate language as argument. This can be accomplished by - modifying the ‘org-latex-packages-alist’ variable, e.g., with the - following snippet: - - (add-to-list 'org-latex-packages-alist - '("AUTO" "babel" t ("pdflatex"))) - (add-to-list 'org-latex-packages-alist - '("AUTO" "polyglossia" t ("xelatex" "lualatex"))) - -‘LATEX_CLASS’ - This is LaTeX document class, such as _article_, _report_, _book_, - and so on, which contain predefined preamble and headline level - mapping that the LaTeX export back-end needs. The back-end reads - the default class name from the ‘org-latex-default-class’ variable. - Org has _article_ as the default class. A valid default class must - be an element of ‘org-latex-classes’. - -‘LATEX_CLASS_OPTIONS’ - Options the LaTeX export back-end uses when calling the LaTeX - document class. - -‘LATEX_COMPILER’ - The compiler, such as ‘pdflatex’, ‘xelatex’, ‘lualatex’, for - producing the PDF. See ‘org-latex-compiler’. - -‘LATEX_HEADER’ -‘LATEX_HEADER_EXTRA’ - Arbitrary lines to add to the document’s preamble, before the - hyperref settings. See ‘org-latex-classes’ for adjusting the - structure and order of the LaTeX headers. - -‘KEYWORDS’ - The keywords for the document. The description along with author - name, keywords, and related file metadata are inserted in the - output file by the hyperref package. See - ‘org-latex-hyperref-template’ for customizing metadata items. See - ‘org-latex-title-command’ for typesetting description into the - document’s front matter. Use multiple ‘KEYWORDS’ lines if - necessary. - -‘SUBTITLE’ - The document’s subtitle. It is typeset as per - ‘org-latex-subtitle-format’. If ‘org-latex-subtitle-separate’ is - non-‘nil’, it is typed outside of the ‘\title’ macro. See - ‘org-latex-hyperref-template’ for customizing metadata items. See - ‘org-latex-title-command’ for typesetting description into the - document’s front matter. - - The following sections have further details. - - -File: org.info, Node: LaTeX header and sectioning, Next: Quoting LaTeX code, Prev: LaTeX specific export settings, Up: LaTeX Export - -13.10.3 LaTeX header and sectioning structure ---------------------------------------------- - -The LaTeX export back-end converts the first three of Org’s outline -levels into LaTeX headlines. The remaining Org levels are exported as -lists. To change this globally for the cut-off point between levels and -lists, (see *note Export Settings::). - - By default, the LaTeX export back-end uses the _article_ class. - - To change the default class globally, edit ‘org-latex-default-class’. -To change the default class locally in an Org file, add option lines -‘#+LATEX_CLASS: myclass’. To change the default class for just a part -of the Org file, set a sub-tree property, ‘EXPORT_LATEX_CLASS’. The -class name entered here must be valid member of ‘org-latex-classes’. -This variable defines a header template for each class into which the -exporter splices the values of ‘org-latex-default-packages-alist’ and -‘org-latex-packages-alist’. Use the same three variables to define -custom sectioning or custom classes. - - The LaTeX export back-end sends the ‘LATEX_CLASS_OPTIONS’ keyword and -‘EXPORT_LATEX_CLASS_OPTIONS’ property as options to the LaTeX -‘\documentclass’ macro. The options and the syntax for specifying them, -including enclosing them in square brackets, follow LaTeX conventions. - - #+LATEX_CLASS_OPTIONS: [a4paper,11pt,twoside,twocolumn] - - The LaTeX export back-end appends values from ‘LATEX_HEADER’ and -‘LATEX_HEADER_EXTRA’ keywords to the LaTeX header. The docstring for -‘org-latex-classes’ explains in more detail. Also note that LaTeX -export back-end does not append ‘LATEX_HEADER_EXTRA’ to the header when -previewing LaTeX snippets (see *note Previewing LaTeX fragments::). - - A sample Org file with the above headers: - - #+LATEX_CLASS: article - #+LATEX_CLASS_OPTIONS: [a4paper] - #+LATEX_HEADER: \usepackage{xyz} - - * Headline 1 - some text - * Headline 2 - some more text - - -File: org.info, Node: Quoting LaTeX code, Next: Tables in LaTeX export, Prev: LaTeX header and sectioning, Up: LaTeX Export - -13.10.4 Quoting LaTeX code --------------------------- - -The LaTeX export back-end can insert any arbitrary LaTeX code, see *note -Embedded LaTeX::. There are three ways to embed such code in the Org -file and they all use different quoting syntax. - - Inserting in-line quoted with @ symbols: - - Code embedded in-line @@latex:any arbitrary LaTeX code@@ in a paragraph. - - Inserting as one or more keyword lines in the Org file: - - #+LATEX: any arbitrary LaTeX code - - Inserting as an export block in the Org file, where the back-end -exports any code between begin and end markers: - - #+BEGIN_EXPORT latex - any arbitrary LaTeX code - #+END_EXPORT - - -File: org.info, Node: Tables in LaTeX export, Next: Images in LaTeX export, Prev: Quoting LaTeX code, Up: LaTeX Export - -13.10.5 Tables in LaTeX export ------------------------------- - -The LaTeX export back-end can pass several LaTeX attributes for table -contents and layout. Besides specifying a label (see *note Internal -Links::) and a caption (see *note Captions::), the other valid LaTeX -attributes include: - -‘:mode’ - The LaTeX export back-end wraps the table differently depending on - the mode for accurate rendering of math symbols. Mode is either - ‘table’, ‘math’, ‘inline-math’ or ‘verbatim’. - - For ‘math’ or ‘inline-math’ mode, LaTeX export back-end wraps the - table in a math environment, but every cell in it is exported - as-is. The LaTeX export back-end determines the default mode from - ‘org-latex-default-table-mode’. The LaTeX export back-end merges - contiguous tables in the same mode into a single environment. - -‘:environment’ - Set the default LaTeX table environment for the LaTeX export - back-end to use when exporting Org tables. Common LaTeX table - environments are provided by these packages: tabularx, longtable, - array, tabu, and bmatrix. For packages, such as tabularx and tabu, - or any newer replacements, include them in the - ‘org-latex-packages-alist’ variable so the LaTeX export back-end - can insert the appropriate load package headers in the converted - LaTeX file. Look in the docstring for the - ‘org-latex-packages-alist’ variable for configuring these packages - for LaTeX snippet previews, if any. - -‘:caption’ - Use ‘CAPTION’ keyword to set a simple caption for a table (see - *note Captions::). For custom captions, use ‘:caption’ attribute, - which accepts raw LaTeX code. ‘:caption’ value overrides ‘CAPTION’ - value. - -‘:float’ -‘:placement’ - The table environments by default are not floats in LaTeX. To make - them floating objects use ‘:float’ with one of the following - options: ‘sideways’, ‘multicolumn’, ‘t’, and ‘nil’. - - LaTeX floats can also have additional layout ‘:placement’ - attributes. These are the usual ‘[h t b p ! H]’ permissions - specified in square brackets. Note that for ‘:float sideways’ - tables, the LaTeX export back-end ignores ‘:placement’ attributes. - -‘:align’ -‘:font’ -‘:width’ - The LaTeX export back-end uses these attributes for regular tables - to set their alignments, fonts, and widths. - -‘:spread’ - When ‘:spread’ is non-‘nil’, the LaTeX export back-end spreads or - shrinks the table by the ‘:width’ for tabu and longtabu - environments. ‘:spread’ has no effect if ‘:width’ is not set. - -‘:booktabs’ -‘:center’ -‘:rmlines’ - All three commands are toggles. ‘:booktabs’ brings in modern - typesetting enhancements to regular tables. The booktabs package - has to be loaded through ‘org-latex-packages-alist’. ‘:center’ is - for centering the table. ‘:rmlines’ removes all but the very first - horizontal line made of ASCII characters from “table.el” tables - only. - -‘:math-prefix’ -‘:math-suffix’ -‘:math-arguments’ - The LaTeX export back-end inserts ‘:math-prefix’ string value in a - math environment before the table. The LaTeX export back-end - inserts ‘:math-suffix’ string value in a math environment after the - table. The LaTeX export back-end inserts ‘:math-arguments’ string - value between the macro name and the table’s contents. - ‘:math-arguments’ comes in use for matrix macros that require more - than one argument, such as ‘qbordermatrix’. - - LaTeX table attributes help formatting tables for a wide range of -situations, such as matrix product or spanning multiple pages: - - #+ATTR_LATEX: :environment longtable :align l|lp{3cm}r|l - | ... | ... | - | ... | ... | - - #+ATTR_LATEX: :mode math :environment bmatrix :math-suffix \times - | a | b | - | c | d | - #+ATTR_LATEX: :mode math :environment bmatrix - | 1 | 2 | - | 3 | 4 | - - Set the caption with the LaTeX command -‘\bicaption{HeadingA}{HeadingB}’: - - #+ATTR_LATEX: :caption \bicaption{HeadingA}{HeadingB} - | ... | ... | - | ... | ... | - - -File: org.info, Node: Images in LaTeX export, Next: Plain lists in LaTeX export, Prev: Tables in LaTeX export, Up: LaTeX Export - -13.10.6 Images in LaTeX export ------------------------------- - -The LaTeX export back-end processes image links in Org files that do not -have descriptions, such as these links ‘[[file:img.jpg]]’ or -‘[[./img.jpg]]’, as direct image insertions in the final PDF output. In -the PDF, they are no longer links but actual images embedded on the -page. The LaTeX export back-end uses ‘\includegraphics’ macro to insert -the image. But for TikZ (<http://sourceforge.net/projects/pgf/>) -images, the back-end uses an ‘\input’ macro wrapped within a -‘tikzpicture’ environment. - - For specifying image ‘:width’, ‘:height’, ‘:scale’ and other -‘:options’, use this syntax: - - #+ATTR_LATEX: :width 5cm :options angle=90 - [[./img/sed-hr4049.pdf]] - - A ‘:scale’ attribute overrides both ‘:width’ and ‘:height’ -attributes. - - For custom commands for captions, use the ‘:caption’ attribute. It -overrides the default ‘#+CAPTION’ value: - - #+ATTR_LATEX: :caption \bicaption{HeadingA}{HeadingB} - [[./img/sed-hr4049.pdf]] - - When captions follow the method as described in *note Captions::, the -LaTeX export back-end wraps the picture in a floating ‘figure’ -environment. To float an image without specifying a caption, set the -‘:float’ attribute to one of the following: - -‘t’ - For a standard ‘figure’ environment; used by default whenever an - image has a caption. - -‘multicolumn’ - To span the image across multiple columns of a page; the back-end - wraps the image in a ‘figure*’ environment. - -‘wrap’ - For text to flow around the image on the right; the figure occupies - the left half of the page. - -‘sideways’ - For a new page with the image sideways, rotated ninety degrees, in - a ‘sidewaysfigure’ environment; overrides ‘:placement’ setting. - -‘nil’ - To avoid a ‘:float’ even if using a caption. - - Use the ‘placement’ attribute to modify a floating environment’s -placement. - - #+ATTR_LATEX: :float wrap :width 0.38\textwidth :placement {r}{0.4\textwidth} - [[./img/hst.png]] - - The LaTeX export back-end centers all images by default. Setting -‘:center’ to ‘nil’ disables centering. To disable centering globally, -set ‘org-latex-images-centered’ to ‘nil’. - - Set the ‘:comment-include’ attribute to non-‘nil’ value for the LaTeX -export back-end to comment out the ‘\includegraphics’ macro. - - -File: org.info, Node: Plain lists in LaTeX export, Next: Source blocks in LaTeX export, Prev: Images in LaTeX export, Up: LaTeX Export - -13.10.7 Plain lists in LaTeX export ------------------------------------ - -The LaTeX export back-end accepts the ‘environment’ and ‘options’ -attributes for plain lists. Both attributes work together for -customizing lists, as shown in the examples: - - #+LATEX_HEADER: \usepackage[inline]{enumitem} - Some ways to say "Hello": - #+ATTR_LATEX: :environment itemize* - #+ATTR_LATEX: :options [label={}, itemjoin={,}, itemjoin*={, and}] - - Hola - - Bonjour - - Guten Tag. - - Since LaTeX supports only four levels of nesting for lists, use an -external package, such as ‘enumitem’ in LaTeX, for levels deeper than -four: - - #+LATEX_HEADER: \usepackage{enumitem} - #+LATEX_HEADER: \renewlist{itemize}{itemize}{9} - #+LATEX_HEADER: \setlist[itemize]{label=$\circ$} - - One - - Two - - Three - - Four - - Five - - -File: org.info, Node: Source blocks in LaTeX export, Next: Example blocks in LaTeX export, Prev: Plain lists in LaTeX export, Up: LaTeX Export - -13.10.8 Source blocks in LaTeX export -------------------------------------- - -The LaTeX export back-end can make source code blocks into floating -objects through the attributes ‘:float’ and ‘:options’. For ‘:float’: - -‘t’ - Makes a source block float; by default floats any source block with - a caption. - -‘multicolumn’ - Spans the source block across multiple columns of a page. - -‘nil’ - Avoids a ‘:float’ even if using a caption; useful for source code - blocks that may not fit on a page. - - #+ATTR_LATEX: :float nil - #+BEGIN_SRC emacs-lisp - Lisp code that may not fit in a single page. - #+END_SRC - - The LaTeX export back-end passes string values in ‘:options’ to LaTeX -packages for customization of that specific source block. In the -example below, the ‘:options’ are set for Minted. Minted is a source -code highlighting LaTeX package with many configurable options(1). - - #+ATTR_LATEX: :options commentstyle=\bfseries - #+BEGIN_SRC emacs-lisp - (defun Fib (n) - (if (< n 2) n (+ (Fib (- n 1)) (Fib (- n 2))))) - #+END_SRC - - To apply similar configuration options for all source blocks in a -file, use the ‘org-latex-listings-options’ and -‘org-latex-minted-options’ variables. - - ---------- Footnotes ---------- - - (1) Minted uses an external Python package for code highlighting, -which requires the flag ‘-shell-escape’ to be added to -‘org-latex-pdf-process’. - - -File: org.info, Node: Example blocks in LaTeX export, Next: Special blocks in LaTeX export, Prev: Source blocks in LaTeX export, Up: LaTeX Export - -13.10.9 Example blocks in LaTeX export --------------------------------------- - -The LaTeX export back-end wraps the contents of example blocks in a -‘verbatim’ environment. To change this behavior to use another -environment globally, specify an appropriate export filter (see *note -Advanced Export Configuration::). To change this behavior to use -another environment for each block, use the ‘:environment’ parameter to -specify a custom environment. - - #+ATTR_LATEX: :environment myverbatim - #+BEGIN_EXAMPLE - This sentence is false. - #+END_EXAMPLE - - -File: org.info, Node: Special blocks in LaTeX export, Next: Horizontal rules in LaTeX export, Prev: Example blocks in LaTeX export, Up: LaTeX Export - -13.10.10 Special blocks in LaTeX export ---------------------------------------- - -For other special blocks in the Org file, the LaTeX export back-end -makes a special environment of the same name. The back-end also takes -‘:options’, if any, and appends as-is to that environment’s opening -string. For example: - - #+BEGIN_abstract - We demonstrate how to solve the Syracuse problem. - #+END_abstract - - #+ATTR_LATEX: :options [Proof of important theorem] - #+BEGIN_proof - ... - Therefore, any even number greater than 2 is the sum of two primes. - #+END_proof - -exports to - - \begin{abstract} - We demonstrate how to solve the Syracuse problem. - \end{abstract} - - \begin{proof}[Proof of important theorem] - ... - Therefore, any even number greater than 2 is the sum of two primes. - \end{proof} - - If you need to insert a specific caption command, use ‘:caption’ -attribute. It overrides standard ‘CAPTION’ value, if any. For example: - - #+ATTR_LATEX: :caption \MyCaption{HeadingA} - #+BEGIN_proof - ... - #+END_proof - - -File: org.info, Node: Horizontal rules in LaTeX export, Next: Verse blocks in LaTeX export, Prev: Special blocks in LaTeX export, Up: LaTeX Export - -13.10.11 Horizontal rules in LaTeX export ------------------------------------------ - -The LaTeX export back-end converts horizontal rules by the specified -‘:width’ and ‘:thickness’ attributes. For example: - - #+ATTR_LATEX: :width .6\textwidth :thickness 0.8pt - ----- - - -File: org.info, Node: Verse blocks in LaTeX export, Next: Quote blocks in LaTeX export, Prev: Horizontal rules in LaTeX export, Up: LaTeX Export - -13.10.12 Verse blocks in LaTeX export -------------------------------------- - -The LaTeX export back-end accepts four attributes for verse blocks: -‘:lines’, ‘:center’, ‘:versewidth’ and ‘:latexcode’. The three first -require the external LaTeX package ‘verse.sty’, which is an extension of -the standard LaTeX environment. - -‘:lines’ - To add marginal verse numbering. Its value is an integer, the - sequence in which the verses should be numbered. -‘:center’ - With value ‘t’ all the verses on the page are optically centered (a - typographic convention for poetry), taking as a reference the - longest verse, which must be indicated by the attribute - ‘:versewidth’. -‘:versewidth’ - Its value is a literal text string with the longest verse. -‘:latexcode’ - It accepts any arbitrary LaTeX code that can be included within a - LaTeX ‘verse’ environment. - - A complete example with Shakespeare’s first sonnet: - - #+ATTR_LATEX: :center t :latexcode \color{red} :lines 5 - #+ATTR_LATEX: :versewidth Feed’st thy light’s flame with self-substantial fuel, - #+BEGIN_VERSE - From fairest creatures we desire increase, - That thereby beauty’s rose might never die, - But as the riper should by time decease - His tender heir might bear his memory - But thou, contracted to thine own bright eyes, - Feed’st thy light’s flame with self-substantial fuel, - Making a famine where abundance lies, - Thyself thy foe, to thy sweet self too cruel. - Thou that art now the world’s fresh ornament, - And only herald to the gaudy spring, - Within thine own bud buriest thy content, - And, tender churl, mak’st waste in niggardly. - Pity the world, or else this glutton be, - To eat the world’s due, by the grave and thee. - #+END_VERSE - - -File: org.info, Node: Quote blocks in LaTeX export, Prev: Verse blocks in LaTeX export, Up: LaTeX Export - -13.10.13 Quote blocks in LaTeX export -------------------------------------- - -The LaTeX export back-end accepts two attributes for quote blocks: -‘:environment’, for an arbitrary quoting environment (the default value -is that of ‘org-latex-default-quote-environment’: ‘"quote"’) and -‘:options’. For example, to choose the environment ‘quotation’, -included as an alternative to ‘quote’ in standard LaTeX classes: - - #+ATTR_LATEX: :environment quotation - #+BEGIN_QUOTE - some text... - #+END_QUOTE - - To choose the ‘foreigndisplayquote’ environment, included in the -LaTeX package ‘csquotes’, with the ‘german’ option, use this syntax: - - #+LATEX_HEADER:\usepackage[autostyle=true]{csquotes} - #+ATTR_LATEX: :environment foreigndisplayquote :options {german} - #+BEGIN_QUOTE - some text in German... - #+END_QUOTE - -which is exported to LaTeX as - - \begin{foreigndisplayquote}{german} - some text in German... - \end{foreigndisplayquote} - - -File: org.info, Node: Markdown Export, Next: OpenDocument Text Export, Prev: LaTeX Export, Up: Exporting - -13.11 Markdown Export -===================== - -The Markdown export back-end, “md”, converts an Org file to Markdown -format, as defined at <http://daringfireball.net/projects/markdown/>. - - Since it is built on top of the HTML back-end (see *note HTML -Export::), it converts every Org construct not defined in Markdown -syntax, such as tables, to HTML. - -Markdown export commands ------------------------- - -‘C-c C-e m m’ (‘org-md-export-to-markdown’) - Export to a text file with Markdown syntax. For ‘myfile.org’, Org - exports to ‘myfile.md’, overwritten without warning. - -‘C-c C-e m M’ (‘org-md-export-as-markdown’) - Export to a temporary buffer. Does not create a file. - -‘C-c C-e m o’ - Export as a text file with Markdown syntax, then open it. - -Header and sectioning structure -------------------------------- - -Based on ‘org-md-headline-style’, Markdown export can generate headlines -of both _atx_ and _setext_ types. _atx_ limits headline levels to two -whereas _setext_ limits headline levels to six. Beyond these limits, -the export back-end converts headlines to lists. To set a limit to a -level before the absolute limit (see *note Export Settings::). - - -File: org.info, Node: OpenDocument Text Export, Next: Org Export, Prev: Markdown Export, Up: Exporting - -13.12 OpenDocument Text Export -============================== - -The ODT export back-end handles creating of OpenDocument Text (ODT) -format. Documents created by this exporter use the ‘OpenDocument-v1.2 -specification’(1) and are compatible with LibreOffice 3.4. - -* Menu: - -* Pre-requisites for ODT export:: Required packages. -* ODT export commands:: Invoking export. -* ODT specific export settings:: Configuration options. -* Extending ODT export:: Producing DOC, PDF files. -* Applying custom styles:: Styling the output. -* Links in ODT export:: Handling and formatting links. -* Tables in ODT export:: Org tables conversions. -* Images in ODT export:: Inserting images. -* Math formatting in ODT export:: Formatting LaTeX fragments. -* Labels and captions in ODT export:: Rendering objects. -* Literal examples in ODT export:: For source code and example blocks. -* Advanced topics in ODT export:: For power users. - - ---------- Footnotes ---------- - - (1) See Open Document Format for Office Applications (OpenDocument) -Version 1.2 -(http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html). - - -File: org.info, Node: Pre-requisites for ODT export, Next: ODT export commands, Up: OpenDocument Text Export - -13.12.1 Pre-requisites for ODT export -------------------------------------- - -The ODT export back-end relies on the zip program to create the final -compressed ODT output. Check if ‘zip’ is locally available and -executable. Without it, export cannot finish. - - -File: org.info, Node: ODT export commands, Next: ODT specific export settings, Prev: Pre-requisites for ODT export, Up: OpenDocument Text Export - -13.12.2 ODT export commands ---------------------------- - -‘C-c C-e o o’ (‘org-export-to-odt’) - Export as OpenDocument Text file. - - If ‘org-odt-preferred-output-format’ is specified, the ODT export - back-end automatically converts the exported file to that format. - - For ‘myfile.org’, Org exports to ‘myfile.odt’, overwriting without - warning. The ODT export back-end exports a region only if a region - was active. - - If the selected region is a single tree, the ODT export back-end - makes the tree head the document title. Incidentally, ‘C-c @’ - selects the current sub-tree. If the tree head entry has, or - inherits, an ‘EXPORT_FILE_NAME’ property, the ODT export back-end - uses that for file name. - -‘C-c C-e o O’ - Export as an OpenDocument Text file and open the resulting file. - - If ‘org-export-odt-preferred-output-format’ is specified, open the - converted file instead. See *note Automatically exporting to other - formats::. - - -File: org.info, Node: ODT specific export settings, Next: Extending ODT export, Prev: ODT export commands, Up: OpenDocument Text Export - -13.12.3 ODT specific export settings ------------------------------------- - -The ODT export back-end has several additional keywords for customizing -ODT output. Setting these keywords works similar to the general options -(see *note Export Settings::). - -‘DESCRIPTION’ - This is the document’s description, which the ODT export back-end - inserts as document metadata. For long descriptions, use multiple - lines, prefixed with ‘DESCRIPTION’. - -‘KEYWORDS’ - The keywords for the document. The ODT export back-end inserts the - description along with author name, keywords, and related file - metadata as metadata in the output file. Use multiple ‘KEYWORDS’ - if necessary. - -‘ODT_STYLES_FILE’ - The ODT export back-end uses the ‘org-odt-styles-file’ by default. - See *note Applying custom styles:: for details. - -‘SUBTITLE’ - The document subtitle. - - -File: org.info, Node: Extending ODT export, Next: Applying custom styles, Prev: ODT specific export settings, Up: OpenDocument Text Export - -13.12.4 Extending ODT export ----------------------------- - -The ODT export back-end can produce documents in other formats besides -ODT using a specialized ODT converter process. Its common interface -works with popular converters to produce formats such as ‘doc’, or -convert a document from one format, say ‘csv’, to another format, say -‘xls’. - - Customize ‘org-odt-convert-process’ variable to point to ‘unoconv’, -which is the ODT’s preferred converter. Working installations of -LibreOffice would already have ‘unoconv’ installed. Alternatively, -other converters may be substituted here. See *note Configuring a -document converter::. - -Automatically exporting to other formats -........................................ - -If ODT format is just an intermediate step to get to other formats, such -as ‘doc’, ‘docx’, ‘rtf’, or ‘pdf’, etc., then extend the ODT export -back-end to directly produce that format. Specify the final format in -the ‘org-odt-preferred-output-format’ variable. This is one way to -extend (see *note ODT export commands::). - -Converting between document formats -................................... - -The Org export back-end is made to be inter-operable with a wide range -of text document format converters. Newer generation converters, such -as LibreOffice and Pandoc, can handle hundreds of formats at once. Org -provides a consistent interaction with whatever converter is installed. -Here are some generic commands: - -‘M-x org-odt-convert’ - Convert an existing document from one format to another. With a - prefix argument, opens the newly produced file. - - -File: org.info, Node: Applying custom styles, Next: Links in ODT export, Prev: Extending ODT export, Up: OpenDocument Text Export - -13.12.5 Applying custom styles ------------------------------- - -The ODT export back-end comes with many OpenDocument styles (see *note -Working with OpenDocument style files::). To expand or further -customize these built-in style sheets, either edit the style sheets -directly or generate them using an application such as LibreOffice. The -example here shows creating a style using LibreOffice. - -Applying custom styles: the easy way -.................................... - - 1. Create a sample ‘example.org’ file with settings as shown below, - and export it to ODT format. - - #+OPTIONS: H:10 num:t - - 2. Open the above ‘example.odt’ using LibreOffice. Use the _Stylist_ - to locate the target styles, which typically have the “Org” prefix. - Open one, modify, and save as either OpenDocument Text (ODT) or - OpenDocument Template (OTT) file. - - 3. Customize the variable ‘org-odt-styles-file’ and point it to the - newly created file. For additional configuration options, see - *note Overriding factory styles: x-overriding-factory-styles. - - To apply an ODT style to a particular file, use the - ‘ODT_STYLES_FILE’ keyword as shown in the example below: - - #+ODT_STYLES_FILE: "/path/to/example.ott" - - or - - #+ODT_STYLES_FILE: ("/path/to/file.ott" ("styles.xml" "image/hdr.png")) - -Using third-party styles and templates -...................................... - -The ODT export back-end relies on many templates and style names. Using -third-party styles and templates can lead to mismatches. Templates -derived from built in ODT templates and styles seem to have fewer -problems. - - -File: org.info, Node: Links in ODT export, Next: Tables in ODT export, Prev: Applying custom styles, Up: OpenDocument Text Export - -13.12.6 Links in ODT export ---------------------------- - -ODT exporter creates native cross-references for internal links. It -creates Internet-style links for all other links. - - A link with no description and pointing to a regular, un-itemized, -outline heading is replaced with a cross-reference and section number of -the heading. - - A ‘\ref{label}’-style reference to an image, table etc., is replaced -with a cross-reference and sequence number of the labeled entity. See -*note Labels and captions in ODT export::. - - -File: org.info, Node: Tables in ODT export, Next: Images in ODT export, Prev: Links in ODT export, Up: OpenDocument Text Export - -13.12.7 Tables in ODT export ----------------------------- - -The ODT export back-end handles native Org mode tables (see *note -Tables::) and simple ‘table.el’ tables. Complex ‘table.el’ tables -having column or row spans are not supported. Such tables are stripped -from the exported document. - - By default, the ODT export back-end exports a table with top and -bottom frames and with ruled lines separating row and column groups (see -*note Column Groups::). All tables are typeset to occupy the same -width. The ODT export back-end honors any table alignments and relative -widths for columns (see *note Column Width and Alignment::). - - Note that the ODT export back-end interprets column widths as -weighted ratios, the default weight being 1. - - Specifying ‘:rel-width’ property on an ‘ATTR_ODT’ line controls the -width of the table. For example: - - #+ATTR_ODT: :rel-width 50 - | Area/Month | Jan | Feb | Mar | Sum | - |---------------+-------+-------+-------+-------| - | / | < | | | < | - | <l13> | <r5> | <r5> | <r5> | <r6> | - | North America | 1 | 21 | 926 | 948 | - | Middle East | 6 | 75 | 844 | 925 | - | Asia Pacific | 9 | 27 | 790 | 826 | - |---------------+-------+-------+-------+-------| - | Sum | 16 | 123 | 2560 | 2699 | - - On export, the above table takes 50% of text width area. The -exporter sizes the columns in the ratio: 13:5:5:5:6. The first column -is left-aligned and rest of the columns, right-aligned. Vertical rules -separate the header and the last column. Horizontal rules separate the -header and the last row. - - For even more customization, create custom table styles and associate -them with a table using the ‘ATTR_ODT’ keyword. See *note Customizing -tables in ODT export::. - - -File: org.info, Node: Images in ODT export, Next: Math formatting in ODT export, Prev: Tables in ODT export, Up: OpenDocument Text Export - -13.12.8 Images in ODT export ----------------------------- - -Embedding images -................ - -The ODT export back-end processes image links in Org files that do not -have descriptions, such as these links ‘[[file:img.jpg]]’ or -‘[[./img.jpg]]’, as direct image insertions in the final output. Either -of these examples works: - - [[file:img.png]] - - [[./img.png]] - -Embedding clickable images -.......................... - -For clickable images, provide a link whose description is another link -to an image file. For example, to embed an image ‘org-mode-unicorn.png’ -which when clicked jumps to <https://orgmode.org> website, do the -following - - [[https://orgmode.org][./org-mode-unicorn.png]] - -Sizing and scaling of embedded images -..................................... - -Control the size and scale of the embedded images with the ‘ATTR_ODT’ -attribute. - - The ODT export back-end starts with establishing the size of the -image in the final document. The dimensions of this size are measured -in centimeters. The back-end then queries the image file for its -dimensions measured in pixels. For this measurement, the back-end -relies on ImageMagick’s identify program or Emacs ‘create-image’ and -‘image-size’ API. ImageMagick is the preferred choice for large file -sizes or frequent batch operations. The back-end then converts the -pixel dimensions using ‘org-odt-pixels-per-inch’ into the familiar 72 -dpi or 96 dpi. The default value for this is in -‘display-pixels-per-inch’, which can be tweaked for better results based -on the capabilities of the output device. Here are some common image -scaling operations: - -Explicitly size the image - To embed ‘img.png’ as a 10 cm x 10 cm image, do the following: - - #+ATTR_ODT: :width 10 :height 10 - [[./img.png]] - -Scale the image - To embed ‘img.png’ at half its size, do the following: - - #+ATTR_ODT: :scale 0.5 - [[./img.png]] - -Scale the image to a specific width - To embed ‘img.png’ with a width of 10 cm while retaining the - original height:width ratio, do the following: - - #+ATTR_ODT: :width 10 - [[./img.png]] - -Scale the image to a specific height - To embed ‘img.png’ with a height of 10 cm while retaining the - original height:width ratio, do the following: - - #+ATTR_ODT: :height 10 - [[./img.png]] - -Anchoring of images -................... - -The ODT export back-end can anchor images to ‘as-char’, ‘paragraph’, or -‘page’. Set the preferred anchor using the ‘:anchor’ property of the -‘ATTR_ODT’ line. - - To create an image that is anchored to a page: - - #+ATTR_ODT: :anchor page - [[./img.png]] - - -File: org.info, Node: Math formatting in ODT export, Next: Labels and captions in ODT export, Prev: Images in ODT export, Up: OpenDocument Text Export - -13.12.9 Math formatting in ODT export -------------------------------------- - -The ODT exporter has special support for handling math. - -* Menu: - -* LaTeX math snippets:: Embedding in LaTeX format. -* MathML and OpenDocument formula files:: Embedding in native format. - - -File: org.info, Node: LaTeX math snippets, Next: MathML and OpenDocument formula files, Up: Math formatting in ODT export - -13.12.9.1 LaTeX math snippets -............................. - -LaTeX math snippets (see *note LaTeX fragments::) can be embedded in the -ODT document in one of the following ways: - -MathML - Add this line to the Org file. This option is activated on a - per-file basis. - - #+OPTIONS: tex:t - - With this option, LaTeX fragments are first converted into MathML - fragments using an external LaTeX-to-MathML converter program. The - resulting MathML fragments are then embedded as an OpenDocument - Formula in the exported document. - - You can specify the LaTeX-to-MathML converter by customizing the - variables ‘org-latex-to-mathml-convert-command’ and - ‘org-latex-to-mathml-jar-file’. - - If you prefer to use MathToWeb(1) as your converter, you can - configure the above variables as shown below. - - (setq org-latex-to-mathml-convert-command - "java -jar %j -unicode -force -df %o %I" - org-latex-to-mathml-jar-file - "/path/to/mathtoweb.jar") - - or, to use LaTeXML(2) instead, - - (setq org-latex-to-mathml-convert-command - "latexmlmath \"%i\" --presentationmathml=%o") - - To quickly verify the reliability of the LaTeX-to-MathML converter, - use the following commands: - - ‘M-x org-export-as-odf’ - Convert a LaTeX math snippet to an OpenDocument formula - (‘.odf’) file. - - ‘M-x org-export-as-odf-and-open’ - Convert a LaTeX math snippet to an OpenDocument formula - (‘.odf’) file and open the formula file with the - system-registered application. - -PNG images - Add this line to the Org file. This option is activated on a - per-file basis. - - #+OPTIONS: tex:dvipng - - #+OPTIONS: tex:dvisvgm - - or - - #+OPTIONS: tex:imagemagick - - Under this option, LaTeX fragments are processed into PNG or SVG - images and the resulting images are embedded in the exported - document. This method requires dvipng program, dvisvgm or - ImageMagick programs. - - ---------- Footnotes ---------- - - (1) See MathToWeb -(http://www.mathtoweb.com/cgi-bin/mathtoweb_home.pl). - - (2) See <http://dlmf.nist.gov/LaTeXML/>. - - -File: org.info, Node: MathML and OpenDocument formula files, Prev: LaTeX math snippets, Up: Math formatting in ODT export - -13.12.9.2 MathML and OpenDocument formula files -............................................... - -When embedding LaTeX math snippets in ODT documents is not reliable, -there is one more option to try. Embed an equation by linking to its -MathML (‘.mml’) source or its OpenDocument formula (‘.odf’) file as -shown below: - - [[./equation.mml]] - -or - - [[./equation.odf]] - - -File: org.info, Node: Labels and captions in ODT export, Next: Literal examples in ODT export, Prev: Math formatting in ODT export, Up: OpenDocument Text Export - -13.12.10 Labels and captions in ODT export ------------------------------------------- - -ODT format handles labeling and captioning of objects based on their -types. Inline images, tables, LaTeX fragments, and Math formulas are -numbered and captioned separately. Each object also gets a unique -sequence number based on its order of first appearance in the Org file. -Each category has its own sequence. A caption is just a label applied -to these objects. - - #+CAPTION: Bell curve - #+NAME: fig:SED-HR4049 - [[./img/a.png]] - - When rendered, it may show as follows in the exported document: - - Figure 2: Bell curve - - To modify the category component of the caption, customize the option -‘org-odt-category-map-alist’. For example, to tag embedded images with -the string “Illustration” instead of the default string “Figure”, use -the following setting: - - (setq org-odt-category-map-alist - '(("__Figure__" "Illustration" "value" "Figure" org-odt--enumerable-image-p))) - - With the above modification, the previous example changes to: - - Illustration 2: Bell curve - - -File: org.info, Node: Literal examples in ODT export, Next: Advanced topics in ODT export, Prev: Labels and captions in ODT export, Up: OpenDocument Text Export - -13.12.11 Literal examples in ODT export ---------------------------------------- - -The ODT export back-end supports literal examples (see *note Literal -Examples::) with full fontification. Internally, the ODT export -back-end relies on ‘htmlfontify.el’ to generate the style definitions -needed for fancy listings. The auto-generated styles get ‘OrgSrc’ -prefix and inherit colors from the faces used by Emacs Font Lock library -for that source language. - - For custom fontification styles, customize the -‘org-odt-create-custom-styles-for-srcblocks’ option. - - To turn off fontification of literal examples, customize the -‘org-odt-fontify-srcblocks’ option. - - -File: org.info, Node: Advanced topics in ODT export, Prev: Literal examples in ODT export, Up: OpenDocument Text Export - -13.12.12 Advanced topics in ODT export --------------------------------------- - -The ODT export back-end has extensive features useful for power users -and frequent uses of ODT formats. - -Configuring a document converter -................................ - -The ODT export back-end works with popular converters with little or no -extra configuration. See *note Extending ODT export::. The following -is for unsupported converters or tweaking existing defaults. - -Register the converter - Add the name of the converter to the ‘org-odt-convert-processes’ - variable. Note that it also requires how the converter is invoked - on the command line. See the variable’s docstring for details. - -Configure its capabilities - Specify which formats the converter can handle by customizing the - variable ‘org-odt-convert-capabilities’. Use the entry for the - default values in this variable for configuring the new converter. - Also see its docstring for details. - -Choose the converter - Select the newly added converter as the preferred one by - customizing the option ‘org-odt-convert-process’. - -Working with OpenDocument style files -..................................... - -This section explores the internals of the ODT exporter; the means by -which it produces styled documents; the use of automatic and custom -OpenDocument styles. - - The ODT exporter relies on two files for generating its output. -These files are bundled with the distribution under the directory -pointed to by the variable ‘org-odt-styles-dir’. The two files are: - -‘OrgOdtStyles.xml’ - This file contributes to the ‘styles.xml’ file of the final ODT - document. This file gets modified for the following purposes: - - 1. To control outline numbering based on user settings; - - 2. To add styles generated by ‘htmlfontify.el’ for fontification - of code blocks. - -‘OrgOdtContentTemplate.xml’ - This file contributes to the ‘content.xml’ file of the final ODT - document. The contents of the Org outline are inserted between the - ‘<office:text>’ ... ‘</office:text>’ elements of this file. - - Apart from serving as a template file for the final ‘content.xml’, - the file serves the following purposes: - - 1. It contains automatic styles for formatting of tables which - are referenced by the exporter; - - 2. It contains ‘<text:sequence-decl>’ ... ‘</text:sequence-decl>’ - elements that control numbering of tables, images, equations, - and similar entities. - - The following two variables control the location from where the ODT -exporter picks up the custom styles and content template files. -Customize these variables to override the factory styles used by the -exporter. - -‘org-odt-styles-file’ - The ODT export back-end uses the file pointed to by this variable, - such as ‘styles.xml’, for the final output. It can take one of the - following values: - - ‘FILE.xml’ - Use this file instead of the default ‘styles.xml’ - - ‘FILE.odt’ or ‘FILE.ott’ - Use the ‘styles.xml’ contained in the specified OpenDocument - Text or Template file - - ‘FILE.odt’ or ‘FILE.ott’ and a subset of included files - Use the ‘styles.xml’ contained in the specified OpenDocument - Text or Template file. Additionally extract the specified - member files and embed those within the final ODT document. - - Use this option if the ‘styles.xml’ file references additional - files like header and footer images. - - ‘nil’ - Use the default ‘styles.xml’. - -‘org-odt-content-template-file’ - Use this variable to specify the blank ‘content.xml’ used in the - final output. - -Creating one-off styles -....................... - -The ODT export back-end can read embedded raw OpenDocument XML from the -Org file. Such direct formatting is useful for one-off instances. - -Embedding ODT tags as part of regular text - Enclose OpenDocument syntax in ‘@@odt:...@@’ for inline markup. - For example, to highlight a region of text do the following: - - @@odt:<text:span text:style-name="Highlight">This is highlighted - text</text:span>@@. But this is regular text. - - *Hint:* To see the above example in action, edit the ‘styles.xml’ - (see *note Factory styles: x-orgodtstyles-xml.) and add a custom - _Highlight_ style as shown below: - - <style:style style:name="Highlight" style:family="text"> - <style:text-properties fo:background-color="#ff0000"/> - </style:style> - -Embedding a one-line OpenDocument XML - The ODT export back-end can read one-liner options with ‘#+ODT:’ in - the Org file. For example, to force a page break: - - #+ODT: <text:p text:style-name="PageBreak"/> - - *Hint:* To see the above example in action, edit your ‘styles.xml’ - (see *note Factory styles: x-orgodtstyles-xml.) and add a custom - ‘PageBreak’ style as shown below. - - <style:style style:name="PageBreak" style:family="paragraph" - style:parent-style-name="Text_20_body"> - <style:paragraph-properties fo:break-before="page"/> - </style:style> - -Embedding a block of OpenDocument XML - The ODT export back-end can also read ODT export blocks for - OpenDocument XML. Such blocks use the ‘#+BEGIN_EXPORT odt’ ... - ‘#+END_EXPORT’ constructs. - - For example, to create a one-off paragraph that uses bold text, do - the following: - - #+BEGIN_EXPORT odt - <text:p text:style-name="Text_20_body_20_bold"> - This paragraph is specially formatted and uses bold text. - </text:p> - #+END_EXPORT - -Customizing tables in ODT export -................................ - -Override the default table format by specifying a custom table style -with the ‘#+ATTR_ODT’ line. For a discussion on default formatting of -tables, see *note Tables in ODT export::. - - This feature closely mimics the way table templates are defined in -the OpenDocument-v1.2 specification(1). - - For quick preview of this feature, install the settings below and -export the table that follows: - - (setq org-export-odt-table-styles - (append org-export-odt-table-styles - '(("TableWithHeaderRowAndColumn" "Custom" - ((use-first-row-styles . t) - (use-first-column-styles . t))) - ("TableWithFirstRowandLastRow" "Custom" - ((use-first-row-styles . t) - (use-last-row-styles . t)))))) - - #+ATTR_ODT: :style TableWithHeaderRowAndColumn - | Name | Phone | Age | - | Peter | 1234 | 17 | - | Anna | 4321 | 25 | - - The example above used ‘Custom’ template and installed two table -styles ‘TableWithHeaderRowAndColumn’ and ‘TableWithFirstRowandLastRow’. -*Important:* The OpenDocument styles needed for producing the above -template were pre-defined. They are available in the section marked -‘Custom Table Template’ in ‘OrgOdtContentTemplate.xml’ (see *note -Factory styles: x-orgodtcontenttemplate-xml.). For adding new -templates, define new styles there. - - To use this feature proceed as follows: - - 1. Create a table template(2). - - A table template is set of ‘table-cell’ and ‘paragraph’ styles for - each of the following table cell categories: - - • Body - • First column - • Last column - • First row - • Last row - • Even row - • Odd row - • Even column - • Odd Column - - The names for the above styles must be chosen based on the name of - the table template using a well-defined convention. - - The naming convention is better illustrated with an example. For a - table template with the name ‘Custom’, the needed style names are - listed in the following table. - - Cell type Cell style Paragraph style - ---------------------------------------------------------------------------------- - Body ‘CustomTableCell’ ‘CustomTableParagraph’ - First column ‘CustomFirstColumnTableCell’ ‘CustomFirstColumnTableParagraph’ - Last column ‘CustomLastColumnTableCell’ ‘CustomLastColumnTableParagraph’ - First row ‘CustomFirstRowTableCell’ ‘CustomFirstRowTableParagraph’ - Last row ‘CustomLastRowTableCell’ ‘CustomLastRowTableParagraph’ - Even row ‘CustomEvenRowTableCell’ ‘CustomEvenRowTableParagraph’ - Odd row ‘CustomOddRowTableCell’ ‘CustomOddRowTableParagraph’ - Even column ‘CustomEvenColumnTableCell’ ‘CustomEvenColumnTableParagraph’ - Odd column ‘CustomOddColumnTableCell’ ‘CustomOddColumnTableParagraph’ - - To create a table template with the name ‘Custom’, define the above - styles in the ‘<office:automatic-styles>’ ... - ‘</office:automatic-styles>’ element of the content template file - (see *note Factory styles: x-orgodtcontenttemplate-xml.). - - 2. Define a table style(3). - - To define a table style, create an entry for the style in the - variable ‘org-odt-table-styles’ and specify the following: - - • the name of the table template created in step (1), - • the set of cell styles in that template that are to be - activated. - - For example, the entry below defines two different table styles - ‘TableWithHeaderRowAndColumn’ and ‘TableWithFirstRowandLastRow’ - based on the same template ‘Custom’. The styles achieve their - intended effect by selectively activating the individual cell - styles in that template. - - (setq org-export-odt-table-styles - (append org-export-odt-table-styles - '(("TableWithHeaderRowAndColumn" "Custom" - ((use-first-row-styles . t) - (use-first-column-styles . t))) - ("TableWithFirstRowandLastRow" "Custom" - ((use-first-row-styles . t) - (use-last-row-styles . t)))))) - - 3. Associate a table with the table style. - - To do this, specify the table style created in step (2) as part of - the ‘ATTR_ODT’ line as shown below. - - #+ATTR_ODT: :style TableWithHeaderRowAndColumn - | Name | Phone | Age | - | Peter | 1234 | 17 | - | Anna | 4321 | 25 | - -Validating OpenDocument XML -........................... - -Sometimes ODT format files may not open due to ‘.odt’ file corruption. -To verify if such a file is corrupt, validate it against the -OpenDocument Relax NG Compact (RNC) syntax schema. But first the ‘.odt’ -files have to be decompressed using ‘zip’. Note that ‘.odt’ files are -ZIP archives: *note (emacs)File Archives::. The contents of ODT files -are in XML. For general help with validation—and schema-sensitive -editing—of XML files: *note (nxml-mode)Introduction::. - - Customize ‘org-odt-schema-dir’ to point to a directory with -OpenDocument RNC files and the needed schema-locating rules. The ODT -export back-end takes care of updating the ‘rng-schema-locating-files’. - - ---------- Footnotes ---------- - - (1) OpenDocument-v1.2 Specification -(http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html) - - (2) See the ‘<table:table-template>’ element of the OpenDocument-v1.2 -specification. - - (3) See the attributes ‘table:template-name’, -‘table:use-first-row-styles’, ‘table:use-last-row-styles’, -‘table:use-first-column-styles’, ‘table:use-last-column-styles’, -‘table:use-banding-rows-styles’, and ‘table:use-banding-column-styles’ -of the ‘<table:table>’ element in the OpenDocument-v1.2 specification. - - -File: org.info, Node: Org Export, Next: Texinfo Export, Prev: OpenDocument Text Export, Up: Exporting - -13.13 Org Export -================ - -_org_ export back-end creates a normalized version of the Org document -in current buffer. The exporter evaluates Babel code (see *note -Evaluating Code Blocks::) and removes content specific to other -back-ends. - -Org export commands -------------------- - -‘C-c C-e O o’ (‘org-org-export-to-org’) - Export as an Org file with a ‘.org’ extension. For ‘myfile.org’, - Org exports to ‘myfile.org.org’, overwriting without warning. - -‘C-c C-e O v’ (~~) - Export to an Org file, then open it. - - -File: org.info, Node: Texinfo Export, Next: iCalendar Export, Prev: Org Export, Up: Exporting - -13.14 Texinfo Export -==================== - -* Menu: - -* Texinfo export commands:: Invoking commands. -* Texinfo specific export settings:: Setting the environment. -* Texinfo file header:: Generating the header. -* Texinfo title and copyright page:: Creating preamble pages. -* Info directory file:: Installing a manual in Info file hierarchy. -* Headings and sectioning structure:: Building document structure. -* Indices:: Creating indices. -* Quoting Texinfo code:: Incorporating literal Texinfo code. -* Plain lists in Texinfo export:: List attributes. -* Tables in Texinfo export:: Table attributes. -* Images in Texinfo export:: Image attributes. -* Quotations in Texinfo export:: Quote block attributes. -* Special blocks in Texinfo export:: Special block attributes. -* A Texinfo example:: Processing Org to Texinfo. - - -File: org.info, Node: Texinfo export commands, Next: Texinfo specific export settings, Up: Texinfo Export - -13.14.1 Texinfo export commands -------------------------------- - -‘C-c C-e i t’ (‘org-texinfo-export-to-texinfo’) - Export as a Texinfo file with ‘.texi’ extension. For ‘myfile.org’, - Org exports to ‘myfile.texi’, overwriting without warning. - -‘C-c C-e i i’ (‘org-texinfo-export-to-info’) - Export to Texinfo format first and then process it to make an Info - file. To generate other formats, such as DocBook, customize the - ‘org-texinfo-info-process’ variable. - - -File: org.info, Node: Texinfo specific export settings, Next: Texinfo file header, Prev: Texinfo export commands, Up: Texinfo Export - -13.14.2 Texinfo specific export settings ----------------------------------------- - -The Texinfo export back-end has several additional keywords for -customizing Texinfo output. Setting these keywords works similar to the -general options (see *note Export Settings::). - -‘SUBTITLE’ - The document subtitle. - -‘SUBAUTHOR’ - Additional authors for the document. - -‘TEXINFO_FILENAME’ - The Texinfo filename. - -‘TEXINFO_CLASS’ - The default document class (‘org-texinfo-default-class’), which - must be a member of ‘org-texinfo-classes’. - -‘TEXINFO_HEADER’ - Arbitrary lines inserted at the end of the header. - -‘TEXINFO_POST_HEADER’ - Arbitrary lines inserted after the end of the header. - -‘TEXINFO_DIR_CATEGORY’ - The directory category of the document. - -‘TEXINFO_DIR_TITLE’ - The directory title of the document. - -‘TEXINFO_DIR_DESC’ - The directory description of the document. - -‘TEXINFO_PRINTED_TITLE’ - The printed title of the document. - - -File: org.info, Node: Texinfo file header, Next: Texinfo title and copyright page, Prev: Texinfo specific export settings, Up: Texinfo Export - -13.14.3 Texinfo file header ---------------------------- - -After creating the header for a Texinfo file, the Texinfo back-end -automatically generates a name and destination path for the Info file. -To override this default with a more sensible path and name, specify the -‘TEXINFO_FILENAME’ keyword. - - Along with the output’s file name, the Texinfo header also contains -language details (see *note Export Settings::) and encoding system as -set in the ‘org-texinfo-coding-system’ variable. Insert -‘TEXINFO_HEADER’ keywords for each additional command in the header, for -example: - - #+TEXINFO_HEADER: @synindex - - Instead of repeatedly installing the same set of commands, define a -class in ‘org-texinfo-classes’ once, and then activate it in the -document by setting the ‘TEXINFO_CLASS’ keyword to that class. - - -File: org.info, Node: Texinfo title and copyright page, Next: Info directory file, Prev: Texinfo file header, Up: Texinfo Export - -13.14.4 Texinfo title and copyright page ----------------------------------------- - -The default template for hard copy output has a title page with ‘TITLE’ -and ‘AUTHOR’ keywords (see *note Export Settings::). To replace the -regular title with something different for the printed version, use the -‘TEXINFO_PRINTED_TITLE’ and ‘SUBTITLE’ keywords. Both expect raw -Texinfo code for setting their values. - - If one ‘AUTHOR’ line is not sufficient, add multiple ‘SUBAUTHOR’ -keywords. They have to be set in raw Texinfo code. - - #+AUTHOR: Jane Smith - #+SUBAUTHOR: John Doe - #+TEXINFO_PRINTED_TITLE: This Long Title@@inlinefmt{tex,@*} Is Broken in @TeX{} - - Copying material is defined in a dedicated headline with a non-‘nil’ -‘COPYING’ property. The back-end inserts the contents within a -‘@copying’ command at the beginning of the document. The heading itself -does not appear in the structure of the document. - - Copyright information is printed on the back of the title page. - - * Legalese - :PROPERTIES: - :COPYING: t - :END: - - This is a short example of a complete Texinfo file, version 1.0. - - Copyright \copy 2016 Free Software Foundation, Inc. - - -File: org.info, Node: Info directory file, Next: Headings and sectioning structure, Prev: Texinfo title and copyright page, Up: Texinfo Export - -13.14.5 Info directory file ---------------------------- - -The end result of the Texinfo export process is the creation of an Info -file. This Info file’s metadata has variables for category, title, and -description: ‘TEXINFO_DIR_CATEGORY’, ‘TEXINFO_DIR_TITLE’, and -‘TEXINFO_DIR_DESC’ keywords that establish where in the Info hierarchy -the file fits. - - Here is an example that writes to the Info directory file: - - #+TEXINFO_DIR_CATEGORY: Emacs - #+TEXINFO_DIR_TITLE: Org Mode: (org) - #+TEXINFO_DIR_DESC: Outline-based notes management and organizer - - -File: org.info, Node: Headings and sectioning structure, Next: Indices, Prev: Info directory file, Up: Texinfo Export - -13.14.6 Headings and sectioning structure ------------------------------------------ - -The Texinfo export back-end uses a pre-defined scheme to convert Org -headlines to equivalent Texinfo structuring commands. A scheme like -this maps top-level headlines to numbered chapters tagged as ‘@chapter’ -and lower-level headlines to unnumbered chapters tagged as -‘@unnumbered’. To override such mappings to introduce ‘@part’ or other -Texinfo structuring commands, define a new class in -‘org-texinfo-classes’. Activate the new class with the ‘TEXINFO_CLASS’ -keyword. When no new class is defined and activated, the Texinfo export -back-end defaults to the ‘org-texinfo-default-class’. - - If an Org headline’s level has no associated Texinfo structuring -command, or is below a certain threshold (see *note Export Settings::), -then the Texinfo export back-end makes it into a list item. - - The Texinfo export back-end makes any headline with a non-‘nil’ -‘APPENDIX’ property into an appendix. This happens independent of the -Org headline level or the ‘TEXINFO_CLASS’ keyword. - - The Texinfo export back-end creates a menu entry after the Org -headline for each regular sectioning structure. To override this with a -shorter menu entry, use the ‘ALT_TITLE’ property (see *note Table of -Contents::). Texinfo menu entries also have an option for a longer -‘DESCRIPTION’ property. Here’s an example that uses both to override -the default menu entry: - - * Controlling Screen Display - :PROPERTIES: - :ALT_TITLE: Display - :DESCRIPTION: Controlling Screen Display - :END: - - The text before the first headline belongs to the _Top_ node, i.e., -the node in which a reader enters an Info manual. As such, it is -expected not to appear in printed output generated from the ‘.texi’ -file. See *note (texinfo)The Top Node::, for more information. - - -File: org.info, Node: Indices, Next: Quoting Texinfo code, Prev: Headings and sectioning structure, Up: Texinfo Export - -13.14.7 Indices ---------------- - -The Texinfo export back-end recognizes these indexing keywords if used -in the Org file: ‘CINDEX’, ‘FINDEX’, ‘KINDEX’, ‘PINDEX’, ‘TINDEX’ and -‘VINDEX’. Write their value as verbatim Texinfo code; in particular, -‘{’, ‘}’ and ‘@’ characters need to be escaped with ‘@’ if they do not -belong to a Texinfo command. - - #+CINDEX: Defining indexing entries - - For the back-end to generate an index entry for a headline, set the -‘INDEX’ property to ‘cp’ or ‘vr’. These abbreviations come from Texinfo -that stand for concept index and variable index. The Texinfo manual has -abbreviations for all other kinds of indexes. The back-end exports the -headline as an unnumbered chapter or section command, and then inserts -the index after its contents. - - * Concept Index - :PROPERTIES: - :INDEX: cp - :END: - - -File: org.info, Node: Quoting Texinfo code, Next: Plain lists in Texinfo export, Prev: Indices, Up: Texinfo Export - -13.14.8 Quoting Texinfo code ----------------------------- - -Use any of the following three methods to insert or escape raw Texinfo -code: - - Richard @@texinfo:@sc{@@Stallman@@texinfo:}@@ commence' GNU. - - #+TEXINFO: @need800 - This paragraph is preceded by... - - #+BEGIN_EXPORT texinfo - @auindex Johnson, Mark - @auindex Lakoff, George - #+END_EXPORT - - -File: org.info, Node: Plain lists in Texinfo export, Next: Tables in Texinfo export, Prev: Quoting Texinfo code, Up: Texinfo Export - -13.14.9 Plain lists in Texinfo export -------------------------------------- - -The Texinfo export back-end by default converts description lists in the -Org file using the default command ‘@table’, which results in a table -with two columns. To change this behavior, set ‘:table-type’ attribute -to either ‘ftable’ or ‘vtable’ value. For more information, see *note -(texinfo)Two-column Tables::. - - The Texinfo export back-end by default also applies a text highlight -based on the defaults stored in ‘org-texinfo-table-default-markup’. To -override the default highlight command, specify another one with the -‘:indic’ attribute. - - Org syntax is limited to one entry per list item. Nevertheless, the -Texinfo export back-end can split that entry according to any text -provided through the ‘:sep’ attribute. Each part then becomes a new -entry in the first column of the table. - - The following example illustrates all the attributes above: - - #+ATTR_TEXINFO: :table-type vtable :sep , :indic asis - - foo, bar :: This is the common text for variables foo and bar. - -becomes - - @vtable @asis - @item foo - @itemx bar - This is the common text for variables foo and bar. - @end table - - Ordered lists are numbered when exported to Texinfo format. Such -numbering obeys any counter (see *note Plain Lists::) in the first item -of the list. The ‘:enum’ attribute also let you start the list at a -specific number, or switch to a lettered list, as illustrated here - - #+ATTR_TEXINFO: :enum A - 1. Alpha - 2. Bravo - 3. Charlie - - -File: org.info, Node: Tables in Texinfo export, Next: Images in Texinfo export, Prev: Plain lists in Texinfo export, Up: Texinfo Export - -13.14.10 Tables in Texinfo export ---------------------------------- - -When exporting tables, the Texinfo export back-end uses the widest cell -width in each column. To override this and instead specify as fractions -of line length, use the ‘:columns’ attribute. See example below. - - #+ATTR_TEXINFO: :columns .5 .5 - | a cell | another cell | - - -File: org.info, Node: Images in Texinfo export, Next: Quotations in Texinfo export, Prev: Tables in Texinfo export, Up: Texinfo Export - -13.14.11 Images in Texinfo export ---------------------------------- - -Insert a file link to the image in the Org file, and the Texinfo export -back-end inserts the image. These links must have the usual supported -image extensions and no descriptions. To scale the image, use ‘:width’ -and ‘:height’ attributes. For alternate text, use ‘:alt’ and specify -the text using Texinfo code, as shown in the example: - - #+ATTR_TEXINFO: :width 1in :alt Alternate @i{text} - [[ridt.pdf]] - - -File: org.info, Node: Quotations in Texinfo export, Next: Special blocks in Texinfo export, Prev: Images in Texinfo export, Up: Texinfo Export - -13.14.12 Quotations in Texinfo export -------------------------------------- - -You can write the text of a quotation within a quote block (see *note -Paragraphs::). You may also emphasize some text at the beginning of the -quotation with the ‘:tag’ attribute. - - #+ATTR_TEXINFO: :tag Warning - #+BEGIN_QUOTE - Striking your thumb with a hammer may cause severe pain and discomfort. - #+END_QUOTE - - To specify the author of the quotation, use the ‘:author’ attribute. - - #+ATTR_TEXINFO: :author King Arthur - #+BEGIN_QUOTE - The Lady of the Lake, her arm clad in the purest shimmering samite, - held aloft Excalibur from the bosom of the water, signifying by divine - providence that I, Arthur, was to carry Excalibur. That is why I am - your king. - #+END_QUOTE - - -File: org.info, Node: Special blocks in Texinfo export, Next: A Texinfo example, Prev: Quotations in Texinfo export, Up: Texinfo Export - -13.14.13 Special blocks in Texinfo export ------------------------------------------ - -The Texinfo export back-end converts special blocks to commands with the -same name. It also adds any ‘:options’ attributes to the end of the -command, as shown in this example: - - #+ATTR_TEXINFO: :options org-org-export-to-org ... - #+BEGIN_defun - A somewhat obsessive function name. - #+END_defun - -becomes - - @defun org-org-export-to-org ... - A somewhat obsessive function name. - @end defun - - -File: org.info, Node: A Texinfo example, Prev: Special blocks in Texinfo export, Up: Texinfo Export - -13.14.14 A Texinfo example --------------------------- - -Here is a more detailed example Org file. See *note (texinfo)GNU Sample -Texts:: for an equivalent example using Texinfo code. - - #+TITLE: GNU Sample {{{version}}} - #+SUBTITLE: for version {{{version}}}, {{{updated}}} - #+AUTHOR: A.U. Thor - #+EMAIL: bug-sample@gnu.org - - #+OPTIONS: ':t toc:t author:t email:t - #+LANGUAGE: en - - #+MACRO: version 2.0 - #+MACRO: updated last updated 4 March 2014 - - #+TEXINFO_FILENAME: sample.info - #+TEXINFO_HEADER: @syncodeindex pg cp - - #+TEXINFO_DIR_CATEGORY: Texinfo documentation system - #+TEXINFO_DIR_TITLE: sample: (sample) - #+TEXINFO_DIR_DESC: Invoking sample - - #+TEXINFO_PRINTED_TITLE: GNU Sample - - This manual is for GNU Sample (version {{{version}}}, - {{{updated}}}). - - * Copying - :PROPERTIES: - :COPYING: t - :END: - - This manual is for GNU Sample (version {{{version}}}, - {{{updated}}}), which is an example in the Texinfo documentation. - - Copyright \copy 2016 Free Software Foundation, Inc. - - #+BEGIN_QUOTE - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.3 or any later version published by the Free Software - Foundation; with no Invariant Sections, with no Front-Cover Texts, - and with no Back-Cover Texts. A copy of the license is included in - the section entitled "GNU Free Documentation License". - #+END_QUOTE - - * Invoking sample - - #+PINDEX: sample - #+CINDEX: invoking @command{sample} - - This is a sample manual. There is no sample program to invoke, but - if there were, you could see its basic usage and command line - options here. - - * GNU Free Documentation License - :PROPERTIES: - :APPENDIX: t - :END: - - #+INCLUDE: fdl.org - - * Index - :PROPERTIES: - :INDEX: cp - :END: - - -File: org.info, Node: iCalendar Export, Next: Other Built-in Back-ends, Prev: Texinfo Export, Up: Exporting - -13.15 iCalendar Export -====================== - -A large part of Org mode’s interoperability success is its ability to -easily export to or import from external applications. The iCalendar -export back-end takes calendar data from Org files and exports to the -standard iCalendar format. - - The iCalendar export back-end can also incorporate TODO entries based -on the configuration of the ‘org-icalendar-include-todo’ variable. The -back-end exports plain timestamps as ‘VEVENT’, TODO items as ‘VTODO’, -and also create events from deadlines that are in non-TODO items. The -back-end uses the deadlines and scheduling dates in Org TODO items for -setting the start and due dates for the iCalendar TODO entry. Consult -the ‘org-icalendar-use-deadline’ and ‘org-icalendar-use-scheduled’ -variables for more details. - - For tags on the headline, the iCalendar export back-end makes them -into iCalendar categories. To tweak the inheritance of tags and TODO -states, configure the variable ‘org-icalendar-categories’. To assign -clock alarms based on time, configure the ‘org-icalendar-alarm-time’ -variable. - - The iCalendar format standard requires globally unique identifier—or -UID—for each entry. The iCalendar export back-end creates UIDs during -export. To save a copy of the UID in the Org file set the variable -‘org-icalendar-store-UID’. The back-end looks for the ‘ID’ property of -the entry for re-using the same UID for subsequent exports. - - Since a single Org entry can result in multiple iCalendar -entries—timestamp, deadline, scheduled item, or TODO item—Org adds -prefixes to the UID, depending on which part of the Org entry triggered -the creation of the iCalendar entry. Prefixing ensures UIDs remains -unique, yet enable synchronization programs trace the connections. - -‘C-c C-e c f’ (‘org-icalendar-export-to-ics’) - Create iCalendar entries from the current Org buffer and store them - in the same directory, using a file extension ‘.ics’. - -‘C-c C-e c a’ (‘org-icalendar-export-agenda-files’) - Create iCalendar entries from Org files in ‘org-agenda-files’ and - store in a separate iCalendar file for each Org file. - -‘C-c C-e c c’ (‘org-icalendar-combine-agenda-files’) - Create a combined iCalendar file from Org files in - ‘org-agenda-files’ and write it to - ‘org-icalendar-combined-agenda-file’ file name. - - The iCalendar export back-end includes ‘SUMMARY’, ‘DESCRIPTION’, -‘LOCATION’, ‘TIMEZONE’ and ‘CLASS’ properties from the Org entries when -exporting. To force the back-end to inherit the ‘LOCATION’, ‘TIMEZONE’ -and ‘CLASS’ properties, configure the ‘org-use-property-inheritance’ -variable. - - When Org entries do not have ‘SUMMARY’, ‘DESCRIPTION’, ‘LOCATION’ and -‘CLASS’ properties, the iCalendar export back-end derives the summary -from the headline, and derives the description from the body of the Org -item. The ‘org-icalendar-include-body’ variable limits the maximum -number of characters of the content are turned into its description. - - The ‘TIMEZONE’ property can be used to specify a per-entry time zone, -and is applied to any entry with timestamp information. Time zones -should be specified as per the IANA time zone database format, e.g., -‘Asia/Almaty’. Alternately, the property value can be ‘UTC’, to force -UTC time for this entry only. - - The ‘CLASS’ property can be used to specify a per-entry visibility -class or access restrictions, and is applied to any entry with class -information. The iCalendar standard defines three visibility classes: -‘PUBLIC’ - The entry is publicly visible (this is the default). -‘CONFIDENTIAL’ - Only a limited group of clients get access to the event. -‘PRIVATE’ - The entry can be retrieved only by its owner. - The server should treat unknown class properties the same as -‘PRIVATE’. - - Exporting to iCalendar format depends in large part on the -capabilities of the destination application. Some are more lenient than -others. Consult the Org mode FAQ for advice on specific applications. - - -File: org.info, Node: Other Built-in Back-ends, Next: Advanced Export Configuration, Prev: iCalendar Export, Up: Exporting - -13.16 Other Built-in Back-ends -============================== - -Other export back-ends included with Org are: - - • ‘ox-man.el’: Export to a man page. - - To activate such back-ends, either customize ‘org-export-backends’ or -load directly with ‘(require 'ox-man)’. On successful load, the -back-end adds new keys in the export dispatcher (see *note The Export -Dispatcher::). - - Follow the comment section of such files, for example, ‘ox-man.el’, -for usage and configuration details. - - -File: org.info, Node: Advanced Export Configuration, Next: Export in Foreign Buffers, Prev: Other Built-in Back-ends, Up: Exporting - -13.17 Advanced Export Configuration -=================================== - -Export hooks ------------- - -The export process executes two hooks before the actual exporting -begins. The first hook, ‘org-export-before-processing-hook’, runs -before any expansions of macros, Babel code, and include keywords in the -buffer. The second hook, ‘org-export-before-parsing-hook’, runs before -the buffer is parsed. - - Functions added to these hooks are called with a single argument: the -export back-end actually used, as a symbol. You may use them for heavy -duty structural modifications of the document. For example, you can -remove every headline in the buffer during export like this: - - (defun my-headline-removal (backend) - "Remove all headlines in the current buffer. - BACKEND is the export back-end being used, as a symbol." - (org-map-entries - (lambda () (delete-region (point) (line-beginning-position 2))))) - - (add-hook 'org-export-before-parsing-hook #'my-headline-removal) - -Filters -------- - -Filters are lists of functions to be applied to certain parts for a -given back-end. The output from the first function in the filter is -passed on to the next function in the filter. The final output is the -output from the final function in the filter. - - The Org export process has many filter sets applicable to different -types of objects, plain text, parse trees, export options, and final -output formats. The filters are named after the element type or object -type: ‘org-export-filter-TYPE-functions’, where TYPE is the type -targeted by the filter. Valid types are: - -body bold babel-call -center-block clock code -diary-sexp drawer dynamic-block -entity example-block export-block -export-snippet final-output fixed-width -footnote-definition footnote-reference headline -horizontal-rule inline-babel-call inline-src-block -inlinetask italic item -keyword latex-environment latex-fragment -line-break link node-property -options paragraph parse-tree -plain-list plain-text planning -property-drawer quote-block radio-target -section special-block src-block -statistics-cookie strike-through subscript -superscript table table-cell -table-row target timestamp -underline verbatim verse-block - - Here is an example filter that replaces non-breaking spaces ‘ ’ in -the Org buffer with ‘~’ for the LaTeX back-end. - - (defun my-latex-filter-nobreaks (text backend info) - "Ensure \" \" are properly handled in LaTeX export." - (when (org-export-derived-backend-p backend 'latex) - (replace-regexp-in-string " " "~" text))) - - (add-to-list 'org-export-filter-plain-text-functions - 'my-latex-filter-nobreaks) - - A filter requires three arguments: the code to be transformed, the -name of the back-end, and some optional information about the export -process. The third argument can be safely ignored. Note the use of -‘org-export-derived-backend-p’ predicate that tests for _latex_ back-end -or any other back-end, such as _beamer_, derived from _latex_. - -Defining filters for individual files -------------------------------------- - -The Org export can filter not just for back-ends, but also for specific -files through the ‘BIND’ keyword. Here is an example with two filters; -one removes brackets from time stamps, and the other removes -strike-through text. The filter functions are defined in a code block -in the same Org file, which is a handy location for debugging. - - #+BIND: org-export-filter-timestamp-functions (tmp-f-timestamp) - #+BIND: org-export-filter-strike-through-functions (tmp-f-strike-through) - #+BEGIN_SRC emacs-lisp :exports results :results none - (defun tmp-f-timestamp (s backend info) - (replace-regexp-in-string "&[lg]t;\\|[][]" "" s)) - (defun tmp-f-strike-through (s backend info) "") - #+END_SRC - -Extending an existing back-end ------------------------------- - -Some parts of the conversion process can be extended for certain -elements so as to introduce a new or revised translation. That is how -the HTML export back-end was extended to handle Markdown format. The -extensions work seamlessly so any aspect of filtering not done by the -extended back-end is handled by the original back-end. Of all the -export customization in Org, extending is very powerful as it operates -at the parser level. - - For this example, make the _ascii_ back-end display the language used -in a source code block. Also make it display only when some attribute -is non-‘nil’, like the following: - - #+ATTR_ASCII: :language t - - Then extend ASCII back-end with a custom “my-ascii” back-end. - - (defun my-ascii-src-block (src-block contents info) - "Transcode a SRC-BLOCK element from Org to ASCII. - CONTENTS is nil. INFO is a plist used as a communication - channel." - (if (not (org-export-read-attribute :attr_ascii src-block :language)) - (org-export-with-backend 'ascii src-block contents info) - (concat - (format ",--[ %s ]--\n%s`----" - (org-element-property :language src-block) - (replace-regexp-in-string - "^" "| " - (org-element-normalize-string - (org-export-format-code-default src-block info))))))) - - (org-export-define-derived-backend 'my-ascii 'ascii - :translate-alist '((src-block . my-ascii-src-block))) - - The ‘my-ascii-src-block’ function looks at the attribute above the -current element. If not true, hands over to _ascii_ back-end. If true, -which it is in this example, it creates a box around the code and leaves -room for the inserting a string for language. The last form creates the -new back-end that springs to action only when translating ‘src-block’ -type elements. - - To use the newly defined back-end, evaluate the following from an Org -buffer: - - (org-export-to-buffer 'my-ascii "*Org MY-ASCII Export*") - - Further steps to consider would be an interactive function, -self-installing an item in the export dispatcher menu, and other -user-friendly improvements. - - -File: org.info, Node: Export in Foreign Buffers, Prev: Advanced Export Configuration, Up: Exporting - -13.18 Export in Foreign Buffers -=============================== - -The export back-ends in Org often include commands to convert selected -regions. A convenient feature of this in-place conversion is that the -exported output replaces the original source. Here are such functions: - -‘org-ascii-convert-region-to-ascii’ - Convert the selected region into ASCII. - -‘org-ascii-convert-region-to-utf8’ - Convert the selected region into UTF-8. - -‘org-html-convert-region-to-html’ - Convert the selected region into HTML. - -‘org-latex-convert-region-to-latex’ - Convert the selected region into LaTeX. - -‘org-texinfo-convert-region-to-texinfo’ - Convert the selected region into Texinfo. - -‘org-md-convert-region-to-md’ - Convert the selected region into Markdown. - - In-place conversions are particularly handy for quick conversion of -tables and lists in foreign buffers. For example, in an HTML buffer, -write a list in Org syntax, select it, and convert it to HTML with ‘M-x -org-html-convert-region-to-html’. - -* Menu: - -* Bare HTML:: Exporting HTML without CSS, Javascript, etc. - - -File: org.info, Node: Bare HTML, Up: Export in Foreign Buffers - -13.18.1 Exporting to minimal HTML ---------------------------------- - -If you want to output a minimal HTML file, with no CSS, no Javascript, -no preamble or postamble, here are the variable you would need to set: - - (setq org-html-head "" - org-html-head-extra "" - org-html-head-include-default-style nil - org-html-head-include-scripts nil - org-html-preamble nil - org-html-postamble nil - org-html-use-infojs nil) - - -File: org.info, Node: Publishing, Next: Citation handling, Prev: Exporting, Up: Top - -14 Publishing -************* - -Org includes a publishing management system that allows you to configure -automatic HTML conversion of _projects_ composed of interlinked Org -files. You can also configure Org to automatically upload your exported -HTML pages and related attachments, such as images and source code -files, to a web server. - - You can also use Org to convert files into PDF, or even combine HTML -and PDF conversion so that files are available in both formats on the -server. - - Publishing has been contributed to Org by David O’Toole. - -* Menu: - -* Configuration:: Defining projects. -* Uploading Files:: How to get files up on the server. -* Sample Configuration:: Example projects. -* Triggering Publication:: Publication commands. - - -File: org.info, Node: Configuration, Next: Uploading Files, Up: Publishing - -14.1 Configuration -================== - -Publishing needs significant configuration to specify files, destination -and many other properties of a project. - -* Menu: - -* Project alist:: The central configuration variable. -* Sources and destinations:: From here to there. -* Selecting files:: What files are part of the project? -* Publishing action:: Setting the function doing the publishing. -* Publishing options:: Tweaking HTML/LaTeX export. -* Publishing links:: Which links keep working after publishing? -* Site map:: Generating a list of all pages. -* Generating an index:: An index that reaches across pages. - - -File: org.info, Node: Project alist, Next: Sources and destinations, Up: Configuration - -14.1.1 The variable ‘org-publish-project-alist’ ------------------------------------------------ - -Publishing is configured almost entirely through setting the value of -one variable, called ‘org-publish-project-alist’. Each element of the -list configures one project, and may be in one of the two following -forms: - - ("project-name" :property value :property value ...) - -i.e., a well-formed property list with alternating keys and values, or: - - ("project-name" :components ("project-name" "project-name" ...)) - - In both cases, projects are configured by specifying property values. -A project defines the set of files that are to be published, as well as -the publishing configuration to use when publishing those files. When a -project takes the second form listed above, the individual members of -the ‘:components’ property are taken to be sub-projects, which group -together files requiring different publishing options. When you publish -such a “meta-project”, all the components are also published, in the -sequence given. - - -File: org.info, Node: Sources and destinations, Next: Selecting files, Prev: Project alist, Up: Configuration - -14.1.2 Sources and destinations for files ------------------------------------------ - -Most properties are optional, but some should always be set. In -particular, Org needs to know where to look for source files, and where -to put published files. - -‘:base-directory’ - Directory containing publishing source files. - -‘:publishing-directory’ - Directory where output files are published. You can directly - publish to a webserver using a file name syntax appropriate for the - Emacs tramp package. Or you can publish to a local directory and - use external tools to upload your website (see *note Uploading - Files::). - -‘:preparation-function’ - Function or list of functions to be called before starting the - publishing process, for example, to run ‘make’ for updating files - to be published. Each preparation function is called with a single - argument, the project property list. - -‘:completion-function’ - Function or list of functions called after finishing the publishing - process, for example, to change permissions of the resulting files. - Each completion function is called with a single argument, the - project property list. - - -File: org.info, Node: Selecting files, Next: Publishing action, Prev: Sources and destinations, Up: Configuration - -14.1.3 Selecting files ----------------------- - -By default, all files with extension ‘.org’ in the base directory are -considered part of the project. This can be modified by setting the -following properties - -‘:base-extension’ - Extension—without the dot—of source files. This actually is a - regular expression. Set this to the symbol ‘any’ if you want to - get all files in ‘:base-directory’, even without extension. - -‘:exclude’ - Regular expression to match file names that should not be - published, even though they have been selected on the basis of - their extension. - -‘:include’ - List of files to be included regardless of ‘:base-extension’ and - ‘:exclude’. - -‘:recursive’ - Non-‘nil’ means, check base-directory recursively for files to - publish. - - -File: org.info, Node: Publishing action, Next: Publishing options, Prev: Selecting files, Up: Configuration - -14.1.4 Publishing action ------------------------- - -Publishing means that a file is copied to the destination directory and -possibly transformed in the process. The default transformation is to -export Org files as HTML files, and this is done by the function -‘org-html-publish-to-html’ which calls the HTML exporter (see *note HTML -Export::). But you can also publish your content as PDF files using -‘org-latex-publish-to-pdf’, or as ASCII, Texinfo, etc., using the -corresponding functions. - - If you want to publish the Org file as an ‘.org’ file but with -_archived_, _commented_, and _tag-excluded_ trees removed, use -‘org-org-publish-to-org’. This produces ‘file.org’ and puts it in the -publishing directory. If you want a htmlized version of this file, set -the parameter ‘:htmlized-source’ to ‘t’. It produces ‘file.org.html’ in -the publishing directory(1). - - Other files like images only need to be copied to the publishing -destination; for this you can use ‘org-publish-attachment’. For non-Org -files, you always need to specify the publishing function: - -‘:publishing-function’ - Function executing the publication of a file. This may also be a - list of functions, which are all called in turn. - -‘:htmlized-source’ - Non-‘nil’ means, publish htmlized source. - - The function must accept three arguments: a property list containing -at least a ‘:publishing-directory’ property, the name of the file to be -published, and the path to the publishing directory of the output file. -It should take the specified file, make the necessary transformation, if -any, and place the result into the destination folder. - - ---------- Footnotes ---------- - - (1) If the publishing directory is the same as the source directory, -‘file.org’ is exported as ‘file.org.org’, so you probably do not want to -do this. - - -File: org.info, Node: Publishing options, Next: Publishing links, Prev: Publishing action, Up: Configuration - -14.1.5 Options for the exporters --------------------------------- - -The property list can be used to set many export options for the HTML -and LaTeX exporters. In most cases, these properties correspond to user -variables in Org. The table below lists these properties along with the -variable they belong to. See the documentation string for the -respective variable for details. - - When a property is given a value in ‘org-publish-project-alist’, its -setting overrides the value of the corresponding user variable, if any, -during publishing. Options set within a file (see *note Export -Settings::), however, override everything. - -Generic properties -.................. - -‘:archived-trees’ ‘org-export-with-archived-trees’ -‘:exclude-tags’ ‘org-export-exclude-tags’ -‘:headline-levels’ ‘org-export-headline-levels’ -‘:language’ ‘org-export-default-language’ -‘:preserve-breaks’ ‘org-export-preserve-breaks’ -‘:section-numbers’ ‘org-export-with-section-numbers’ -‘:select-tags’ ‘org-export-select-tags’ -‘:with-author’ ‘org-export-with-author’ -‘:with-broken-links’ ‘org-export-with-broken-links’ -‘:with-clocks’ ‘org-export-with-clocks’ -‘:with-creator’ ‘org-export-with-creator’ -‘:with-date’ ‘org-export-with-date’ -‘:with-drawers’ ‘org-export-with-drawers’ -‘:with-email’ ‘org-export-with-email’ -‘:with-emphasize’ ‘org-export-with-emphasize’ -‘:with-fixed-width’ ‘org-export-with-fixed-width’ -‘:with-footnotes’ ‘org-export-with-footnotes’ -‘:with-latex’ ‘org-export-with-latex’ -‘:with-planning’ ‘org-export-with-planning’ -‘:with-priority’ ‘org-export-with-priority’ -‘:with-properties’ ‘org-export-with-properties’ -‘:with-special-strings’ ‘org-export-with-special-strings’ -‘:with-sub-superscript’ ‘org-export-with-sub-superscripts’ -‘:with-tables’ ‘org-export-with-tables’ -‘:with-tags’ ‘org-export-with-tags’ -‘:with-tasks’ ‘org-export-with-tasks’ -‘:with-timestamps’ ‘org-export-with-timestamps’ -‘:with-title’ ‘org-export-with-title’ -‘:with-toc’ ‘org-export-with-toc’ -‘:with-todo-keywords’ ‘org-export-with-todo-keywords’ - -ASCII specific properties -......................... - -‘:ascii-bullets’ ‘org-ascii-bullets’ -‘:ascii-caption-above’ ‘org-ascii-caption-above’ -‘:ascii-charset’ ‘org-ascii-charset’ -‘:ascii-global-margin’ ‘org-ascii-global-margin’ -‘:ascii-format-drawer-function’ ‘org-ascii-format-drawer-function’ -‘:ascii-format-inlinetask-function’ ‘org-ascii-format-inlinetask-function’ -‘:ascii-headline-spacing’ ‘org-ascii-headline-spacing’ -‘:ascii-indented-line-width’ ‘org-ascii-indented-line-width’ -‘:ascii-inlinetask-width’ ‘org-ascii-inlinetask-width’ -‘:ascii-inner-margin’ ‘org-ascii-inner-margin’ -‘:ascii-links-to-notes’ ‘org-ascii-links-to-notes’ -‘:ascii-list-margin’ ‘org-ascii-list-margin’ -‘:ascii-paragraph-spacing’ ‘org-ascii-paragraph-spacing’ -‘:ascii-quote-margin’ ‘org-ascii-quote-margin’ -‘:ascii-table-keep-all-vertical-lines’ ‘org-ascii-table-keep-all-vertical-lines’ -‘:ascii-table-use-ascii-art’ ‘org-ascii-table-use-ascii-art’ -‘:ascii-table-widen-columns’ ‘org-ascii-table-widen-columns’ -‘:ascii-text-width’ ‘org-ascii-text-width’ -‘:ascii-underline’ ‘org-ascii-underline’ -‘:ascii-verbatim-format’ ‘org-ascii-verbatim-format’ - -Beamer specific properties -.......................... - -‘:beamer-theme’ ‘org-beamer-theme’ -‘:beamer-column-view-format’ ‘org-beamer-column-view-format’ -‘:beamer-environments-extra’ ‘org-beamer-environments-extra’ -‘:beamer-frame-default-options’ ‘org-beamer-frame-default-options’ -‘:beamer-outline-frame-options’ ‘org-beamer-outline-frame-options’ -‘:beamer-outline-frame-title’ ‘org-beamer-outline-frame-title’ -‘:beamer-subtitle-format’ ‘org-beamer-subtitle-format’ - -HTML specific properties -........................ - -‘:html-allow-name-attribute-in-anchors’ ‘org-html-allow-name-attribute-in-anchors’ -‘:html-checkbox-type’ ‘org-html-checkbox-type’ -‘:html-container’ ‘org-html-container-element’ -‘:html-divs’ ‘org-html-divs’ -‘:html-doctype’ ‘org-html-doctype’ -‘:html-extension’ ‘org-html-extension’ -‘:html-footnote-format’ ‘org-html-footnote-format’ -‘:html-footnote-separator’ ‘org-html-footnote-separator’ -‘:html-footnotes-section’ ‘org-html-footnotes-section’ -‘:html-format-drawer-function’ ‘org-html-format-drawer-function’ -‘:html-format-headline-function’ ‘org-html-format-headline-function’ -‘:html-format-inlinetask-function’ ‘org-html-format-inlinetask-function’ -‘:html-head-extra’ ‘org-html-head-extra’ -‘:html-head-include-default-style’ ‘org-html-head-include-default-style’ -‘:html-head-include-scripts’ ‘org-html-head-include-scripts’ -‘:html-head’ ‘org-html-head’ -‘:html-home/up-format’ ‘org-html-home/up-format’ -‘:html-html5-fancy’ ‘org-html-html5-fancy’ -‘:html-indent’ ‘org-html-indent’ -‘:html-infojs-options’ ‘org-html-infojs-options’ -‘:html-infojs-template’ ‘org-html-infojs-template’ -‘:html-inline-image-rules’ ‘org-html-inline-image-rules’ -‘:html-inline-images’ ‘org-html-inline-images’ -‘:html-link-home’ ‘org-html-link-home’ -‘:html-link-org-files-as-html’ ‘org-html-link-org-files-as-html’ -‘:html-link-up’ ‘org-html-link-up’ -‘:html-link-use-abs-url’ ‘org-html-link-use-abs-url’ -‘:html-mathjax-options’ ‘org-html-mathjax-options’ -‘:html-mathjax-template’ ‘org-html-mathjax-template’ -‘:html-equation-reference-format’ ‘org-html-equation-reference-format’ -‘:html-metadata-timestamp-format’ ‘org-html-metadata-timestamp-format’ -‘:html-postamble-format’ ‘org-html-postamble-format’ -‘:html-postamble’ ‘org-html-postamble’ -‘:html-preamble-format’ ‘org-html-preamble-format’ -‘:html-preamble’ ‘org-html-preamble’ -‘:html-self-link-headlines’ ‘org-html-self-link-headlines’ -‘:html-table-align-individual-field’ ‘de{org-html-table-align-individual-fields’ -‘:html-table-attributes’ ‘org-html-table-default-attributes’ -‘:html-table-caption-above’ ‘org-html-table-caption-above’ -‘:html-table-data-tags’ ‘org-html-table-data-tags’ -‘:html-table-header-tags’ ‘org-html-table-header-tags’ -‘:html-table-row-tags’ ‘org-html-table-row-tags’ -‘:html-table-use-header-tags-for-first-column’ ‘org-html-table-use-header-tags-for-first-column’ -‘:html-tag-class-prefix’ ‘org-html-tag-class-prefix’ -‘:html-text-markup-alist’ ‘org-html-text-markup-alist’ -‘:html-todo-kwd-class-prefix’ ‘org-html-todo-kwd-class-prefix’ -‘:html-toplevel-hlevel’ ‘org-html-toplevel-hlevel’ -‘:html-use-infojs’ ‘org-html-use-infojs’ -‘:html-validation-link’ ‘org-html-validation-link’ -‘:html-viewport’ ‘org-html-viewport’ -‘:html-wrap-src-lines’ ‘org-html-wrap-src-lines’ -‘:html-xml-declaration’ ‘org-html-xml-declaration’ - -LaTeX specific properties -......................... - -‘:latex-active-timestamp-format’ ‘org-latex-active-timestamp-format’ -‘:latex-caption-above’ ‘org-latex-caption-above’ -‘:latex-classes’ ‘org-latex-classes’ -‘:latex-class’ ‘org-latex-default-class’ -‘:latex-compiler’ ‘org-latex-compiler’ -‘:latex-default-figure-position’ ‘org-latex-default-figure-position’ -‘:latex-default-table-environment’ ‘org-latex-default-table-environment’ -‘:latex-default-table-mode’ ‘org-latex-default-table-mode’ -‘:latex-diary-timestamp-format’ ‘org-latex-diary-timestamp-format’ -‘:latex-footnote-defined-format’ ‘org-latex-footnote-defined-format’ -‘:latex-footnote-separator’ ‘org-latex-footnote-separator’ -‘:latex-format-drawer-function’ ‘org-latex-format-drawer-function’ -‘:latex-format-headline-function’ ‘org-latex-format-headline-function’ -‘:latex-format-inlinetask-function’ ‘org-latex-format-inlinetask-function’ -‘:latex-hyperref-template’ ‘org-latex-hyperref-template’ -‘:latex-image-default-height’ ‘org-latex-image-default-height’ -‘:latex-image-default-option’ ‘org-latex-image-default-option’ -‘:latex-image-default-width’ ‘org-latex-image-default-width’ -‘:latex-images-centered’ ‘org-latex-images-centered’ -‘:latex-inactive-timestamp-format’ ‘org-latex-inactive-timestamp-format’ -‘:latex-inline-image-rules’ ‘org-latex-inline-image-rules’ -‘:latex-link-with-unknown-path-format’ ‘org-latex-link-with-unknown-path-format’ -‘:latex-listings-langs’ ‘org-latex-listings-langs’ -‘:latex-listings-options’ ‘org-latex-listings-options’ -‘:latex-listings’ ‘org-latex-listings’ -‘:latex-minted-langs’ ‘org-latex-minted-langs’ -‘:latex-minted-options’ ‘org-latex-minted-options’ -‘:latex-prefer-user-labels’ ‘org-latex-prefer-user-labels’ -‘:latex-subtitle-format’ ‘org-latex-subtitle-format’ -‘:latex-subtitle-separate’ ‘org-latex-subtitle-separate’ -‘:latex-table-scientific-notation’ ‘org-latex-table-scientific-notation’ -‘:latex-tables-booktabs’ ‘org-latex-tables-booktabs’ -‘:latex-tables-centered’ ‘org-latex-tables-centered’ -‘:latex-text-markup-alist’ ‘org-latex-text-markup-alist’ -‘:latex-title-command’ ‘org-latex-title-command’ -‘:latex-toc-command’ ‘org-latex-toc-command’ - -Markdown specific properties -............................ - -‘:md-footnote-format’ ‘org-md-footnote-format’ -‘:md-footnotes-section’ ‘org-md-footnotes-section’ -‘:md-headline-style’ ‘org-md-headline-style’ - -ODT specific properties -....................... - -‘:odt-content-template-file’ ‘org-odt-content-template-file’ -‘:odt-display-outline-level’ ‘org-odt-display-outline-level’ -‘:odt-fontify-srcblocks’ ‘org-odt-fontify-srcblocks’ -‘:odt-format-drawer-function’ ‘org-odt-format-drawer-function’ -‘:odt-format-headline-function’ ‘org-odt-format-headline-function’ -‘:odt-format-inlinetask-function’ ‘org-odt-format-inlinetask-function’ -‘:odt-inline-formula-rules’ ‘org-odt-inline-formula-rules’ -‘:odt-inline-image-rules’ ‘org-odt-inline-image-rules’ -‘:odt-pixels-per-inch’ ‘org-odt-pixels-per-inch’ -‘:odt-styles-file’ ‘org-odt-styles-file’ -‘:odt-table-styles’ ‘org-odt-table-styles’ -‘:odt-use-date-fields’ ‘org-odt-use-date-fields’ - -Texinfo specific properties -........................... - -‘:texinfo-active-timestamp-format’ ‘org-texinfo-active-timestamp-format’ -‘:texinfo-classes’ ‘org-texinfo-classes’ -‘:texinfo-class’ ‘org-texinfo-default-class’ -‘:texinfo-table-default-markup’ ‘org-texinfo-table-default-markup’ -‘:texinfo-diary-timestamp-format’ ‘org-texinfo-diary-timestamp-format’ -‘:texinfo-filename’ ‘org-texinfo-filename’ -‘:texinfo-format-drawer-function’ ‘org-texinfo-format-drawer-function’ -‘:texinfo-format-headline-function’ ‘org-texinfo-format-headline-function’ -‘:texinfo-format-inlinetask-function’ ‘org-texinfo-format-inlinetask-function’ -‘:texinfo-inactive-timestamp-format’ ‘org-texinfo-inactive-timestamp-format’ -‘:texinfo-link-with-unknown-path-format’ ‘org-texinfo-link-with-unknown-path-format’ -‘:texinfo-node-description-column’ ‘org-texinfo-node-description-column’ -‘:texinfo-table-scientific-notation’ ‘org-texinfo-table-scientific-notation’ -‘:texinfo-tables-verbatim’ ‘org-texinfo-tables-verbatim’ -‘:texinfo-text-markup-alist’ ‘org-texinfo-text-markup-alist’ - - -File: org.info, Node: Publishing links, Next: Site map, Prev: Publishing options, Up: Configuration - -14.1.6 Publishing links ------------------------ - -To create a link from one Org file to another, you would use something -like ‘[[file:foo.org][The foo]]’ or simply ‘[[file:foo.org]]’ (see *note -External Links::). When published, this link becomes a link to -‘foo.html’. You can thus interlink the pages of your “Org web” project -and the links will work as expected when you publish them to HTML. If -you also publish the Org source file and want to link to it, use an -‘http’ link instead of a ‘file:’ link, because ‘file’ links are -converted to link to the corresponding ‘.html’ file. - - You may also link to related files, such as images. Provided you are -careful with relative file names, and provided you have also configured -Org to upload the related files, these links will work too. See *note -Complex example::, for an example of this usage. - - Eventually, links between published documents can contain some search -options (see *note Search Options::), which will be resolved to the -appropriate location in the linked file. For example, once published to -HTML, the following links all point to a dedicated anchor in ‘foo.html’. - - [[file:foo.org::*heading]] - [[file:foo.org::#custom-id]] - [[file:foo.org::target]] - - -File: org.info, Node: Site map, Next: Generating an index, Prev: Publishing links, Up: Configuration - -14.1.7 Generating a sitemap ---------------------------- - -The following properties may be used to control publishing of a map of -files for a given project. - -‘:auto-sitemap’ - When non-‘nil’, publish a sitemap during - ‘org-publish-current-project’ or ‘org-publish-all’. - -‘:sitemap-filename’ - Filename for output of sitemap. Defaults to ‘sitemap.org’, which - becomes ‘sitemap.html’. - -‘:sitemap-title’ - Title of sitemap page. Defaults to name of file. - -‘:sitemap-format-entry’ - With this option one can tell how a site-map entry is formatted in - the site-map. It is a function called with three arguments: the - file or directory name relative to base directory of the project, - the site-map style and the current project. It is expected to - return a string. Default value turns file names into links and use - document titles as descriptions. For specific formatting needs, - one can use ‘org-publish-find-date’, ‘org-publish-find-title’ and - ‘org-publish-find-property’, to retrieve additional information - about published documents. - -‘:sitemap-function’ - Plug-in function to use for generation of the sitemap. It is - called with two arguments: the title of the site-map and a - representation of the files and directories involved in the project - as a nested list, which can further be transformed using - ‘org-list-to-generic’, ‘org-list-to-subtree’ and alike. Default - value generates a plain list of links to all files in the project. - -‘:sitemap-sort-folders’ - Where folders should appear in the sitemap. Set this to ‘first’ - (default) or ‘last’ to display folders first or last, respectively. - When set to ‘ignore’, folders are ignored altogether. Any other - value mixes files and folders. This variable has no effect when - site-map style is ‘tree’. - -‘:sitemap-sort-files’ - How the files are sorted in the site map. Set this to - ‘alphabetically’ (default), ‘chronologically’ or - ‘anti-chronologically’. ‘chronologically’ sorts the files with - older date first while ‘anti-chronologically’ sorts the files with - newer date first. ‘alphabetically’ sorts the files alphabetically. - The date of a file is retrieved with ‘org-publish-find-date’. - -‘:sitemap-ignore-case’ - Should sorting be case-sensitive? Default ‘nil’. - -‘:sitemap-file-entry-format’ - With this option one can tell how a sitemap’s entry is formatted in - the sitemap. This is a format string with some escape sequences: - ‘%t’ stands for the title of the file, ‘%a’ stands for the author - of the file and ‘%d’ stands for the date of the file. The date is - retrieved with the ‘org-publish-find-date’ function and formatted - with ‘org-publish-sitemap-date-format’. Default ‘%t’. - -‘:sitemap-date-format’ - Format string for the ‘format-time-string’ function that tells how - a sitemap entry’s date is to be formatted. This property bypasses - ‘org-publish-sitemap-date-format’ which defaults to ‘%Y-%m-%d’. - - -File: org.info, Node: Generating an index, Prev: Site map, Up: Configuration - -14.1.8 Generating an index --------------------------- - -Org mode can generate an index across the files of a publishing project. - -‘:makeindex’ - When non-‘nil’, generate in index in the file ‘theindex.org’ and - publish it as ‘theindex.html’. - - The file is created when first publishing a project with the -‘:makeindex’ set. The file only contains a statement ‘#+INCLUDE: -"theindex.inc"’. You can then build around this include statement by -adding a title, style information, etc. - - Index entries are specified with ‘INDEX’ keyword. An entry that -contains an exclamation mark creates a sub item. - - *** Curriculum Vitae - #+INDEX: CV - #+INDEX: Application!CV - - -File: org.info, Node: Uploading Files, Next: Sample Configuration, Prev: Configuration, Up: Publishing - -14.2 Uploading Files -==================== - -For those people already utilizing third party sync tools such as Rsync -or Unison, it might be preferable not to use the built-in remote -publishing facilities of Org mode which rely heavily on Tramp. Tramp, -while very useful and powerful, tends not to be so efficient for -multiple file transfer and has been known to cause problems under heavy -usage. - - Specialized synchronization utilities offer several advantages. In -addition to timestamp comparison, they also do content and -permissions/attribute checks. For this reason you might prefer to -publish your web to a local directory—possibly even _in place_ with your -Org files—and then use Unison or Rsync to do the synchronization with -the remote host. - - Since Unison, for example, can be configured as to which files to -transfer to a certain remote destination, it can greatly simplify the -project publishing definition. Simply keep all files in the correct -location, process your Org files with ‘org-publish’ and let the -synchronization tool do the rest. You do not need, in this scenario, to -include attachments such as JPG, CSS or PNG files in the project -definition since the third-party tool syncs them. - - Publishing to a local directory is also much faster than to a remote -one, so that you can afford more easily to republish entire projects. -If you set ‘org-publish-use-timestamps-flag’ to ‘nil’, you gain the main -benefit of re-including any changed external files such as source -example files you might include with ‘INCLUDE’ keyword. The timestamp -mechanism in Org is not smart enough to detect if included files have -been modified. - - -File: org.info, Node: Sample Configuration, Next: Triggering Publication, Prev: Uploading Files, Up: Publishing - -14.3 Sample Configuration -========================= - -Below we provide two example configurations. The first one is a simple -project publishing only a set of Org files. The second example is more -complex, with a multi-component project. - -* Menu: - -* Simple example:: One-component publishing. -* Complex example:: A multi-component publishing example. - - -File: org.info, Node: Simple example, Next: Complex example, Up: Sample Configuration - -14.3.1 Example: simple publishing configuration ------------------------------------------------ - -This example publishes a set of Org files to the ‘public_html’ directory -on the local machine. - - (setq org-publish-project-alist - '(("org" - :base-directory "~/org/" - :publishing-function org-html-publish-to-html - :publishing-directory "~/public_html" - :section-numbers nil - :with-toc nil - :html-head "<link rel=\"stylesheet\" - href=\"../other/mystyle.css\" - type=\"text/css\"/>"))) - - -File: org.info, Node: Complex example, Prev: Simple example, Up: Sample Configuration - -14.3.2 Example: complex publishing configuration ------------------------------------------------- - -This more complicated example publishes an entire website, including Org -files converted to HTML, image files, Emacs Lisp source code, and style -sheets. The publishing directory is remote and private files are -excluded. - - To ensure that links are preserved, care should be taken to replicate -your directory structure on the web server, and to use relative file -paths. For example, if your Org files are kept in ‘~/org/’ and your -publishable images in ‘~/images/’, you would link to an image with - - file:../images/myimage.png - - On the web server, the relative path to the image should be the same. -You can accomplish this by setting up an ‘images/’ folder in the right -place on the web server, and publishing images to it. - - (setq org-publish-project-alist - '(("orgfiles" - :base-directory "~/org/" - :base-extension "org" - :publishing-directory "/ssh:user@host:~/html/notebook/" - :publishing-function org-html-publish-to-html - :exclude "PrivatePage.org" ;; regexp - :headline-levels 3 - :section-numbers nil - :with-toc nil - :html-head "<link rel=\"stylesheet\" - href=\"../other/mystyle.css\" type=\"text/css\"/>" - :html-preamble t) - - ("images" - :base-directory "~/images/" - :base-extension "jpg\\|gif\\|png" - :publishing-directory "/ssh:user@host:~/html/images/" - :publishing-function org-publish-attachment) - - ("other" - :base-directory "~/other/" - :base-extension "css\\|el" - :publishing-directory "/ssh:user@host:~/html/other/" - :publishing-function org-publish-attachment) - ("website" :components ("orgfiles" "images" "other")))) - - -File: org.info, Node: Triggering Publication, Prev: Sample Configuration, Up: Publishing - -14.4 Triggering Publication -=========================== - -Once properly configured, Org can publish with the following commands: - -‘C-c C-e P x’ (‘org-publish’) - Prompt for a specific project and publish all files that belong to - it. - -‘C-c C-e P p’ (‘org-publish-current-project’) - Publish the project containing the current file. - -‘C-c C-e P f’ (‘org-publish-current-file’) - Publish only the current file. - -‘C-c C-e P a’ (‘org-publish-all’) - Publish every project. - - Org uses timestamps to track when a file has changed. The above -functions normally only publish changed files. You can override this -and force publishing of all files by giving a prefix argument to any of -the commands above, or by customizing the variable -‘org-publish-use-timestamps-flag’. This may be necessary in particular -if files include other files via ‘SETUPFILE’ or ‘INCLUDE’ keywords. - - -File: org.info, Node: Citation handling, Next: Working with Source Code, Prev: Publishing, Up: Top - -15 Citation handling -******************** - -The ‘oc.el’ library provides tooling to handle citations in Org via -“citation processors” that offer some or all of the following -capabilities: - -activate - Fontification, tooltip preview, etc. -follow - At-point actions on citations via ‘org-open-at-point’. -insert - Add and edit citations via ‘org-cite-insert’. -export - Via different libraries for different target formats. - - The user can configure these with ‘org-cite-activate-processor’, -‘org-cite-follow-processor’, ‘org-cite-insert-processor’, and -‘org-cite-export-processors’ respectively. - - The included “basic” processor provides all four capabilities. - -* Menu: - -* Citations:: -* Citation export processors:: - - -File: org.info, Node: Citations, Next: Citation export processors, Up: Citation handling - -15.1 Citations -============== - -Before adding citations, first set one-or-more bibliographies, either -globally with ‘org-cite-global-bibliography’, or locally using one or -more “bibliography” keywords. - - #+bibliography: SomeFile.bib - #+bibliography: /some/other/file.json - #+bibliography: "/some/file/with spaces/in its name.bib" - - One can then insert and edit citations using ‘org-cite-insert’, -called with ‘C-c C-x @’. - - A _citation_ requires one or more citation _key(s)_, elements -identifying a reference in the bibliography. - - • Each citation is surrounded by brackets and uses the ‘cite’ type. - - • Each key starts with the character ‘@’. - - • Each key can be qualified by a _prefix_ (e.g. “see ”) and/or a - _suffix_ (e.g. “p. 123”), giving information useful or necessary fo - the comprehension of the citation but not included in the - reference. - - • A single citation can cite more than one reference ; the keys are - separated by semicolons ; the formatting of such citation groups is - specified by the style. - - • One can also specify a stylistic variation for the citations by - inserting a ‘/’ and a style name between the ‘cite’ keyword and the - colon; this usually makes sense only for the author-year styles. - - [cite/style:common prefix ;prefix @key suffix; ... ; common suffix] - - The only mandatory elements are: - - • The ‘cite’ keyword and the colon. - • The ‘@’ character immediately preceding each key. - • The brackets surrounding the citation(s) (group). - - -File: org.info, Node: Citation export processors, Prev: Citations, Up: Citation handling - -15.2 Citation export processors -=============================== - -Org currently includes the following export processors: - - • Two processors can export to a variety of formats, including - ‘latex’ (and therefore ‘pdf’), ‘html’, ‘odt’ and plain (UTF8) text: - - basic - a basic export processor, well adapted to situations where - backward compatibility is not a requirement and formatting - needs are minimal; - - csl - this export processor uses format files written in Citation - Style Language - (https://en.wikipedia.org/wiki/Citation_Style_Language) via - citeproc-el (https://github.com/andras-simonyi/citeproc-el); - - • In contrast, two other processors target LaTeX and LaTeX-derived - formats exclusively: - - natbib - this export processor uses BibTeX, the historical - bibliographic processor used with LaTeX, thus allowing the use - of data and style files compatible with this processor - (including a large number of publishers’ styles). It uses - citation commands implemented in the LaTeX package ‘natbib’, - allowing more stylistic variants that LaTeX’s ‘\cite’ command. - - biblatex - this backend allows the use of data and formats prepared for - BibLaTeX, an alternate bibliographic processor used with - LaTeX, which overcomes some serious BibTeX limitations, but - has not (yet?) been widely adopted by publishers. - - The ‘CITE_EXPORT’ keyword specifies the export processor and the -citation (and possibly reference) style(s); for example (all arguments -are optional) - - #+cite_export: basic author author-year - -specifies the “basic” export processor with citations inserted as -author’s name and references indexed by author’s names and year; - - #+cite_export: csl /some/path/to/vancouver-brackets.csl - -specifies the “csl” processor and CSL style, which in this case defines -numeric citations and numeric references according to the ‘Vancouver’ -specification (as style used in many medical journals), following a -typesetting variation putting citations between brackets; - - #+cite_export: natbib kluwer - -specifies the ‘natbib’ export processor with a label citation style -conformant to the Harvard style and the specification of the -Wolkers-Kluwer publisher; since it relies on the ‘bibtex’ processor of -your LaTeX installation, it won’t export to anything but PDF. - - -File: org.info, Node: Working with Source Code, Next: Miscellaneous, Prev: Citation handling, Up: Top - -16 Working with Source Code -*************************** - -Source code here refers to any plain text collection of computer -instructions, possibly with comments, written using a human-readable -programming language. Org can manage source code in an Org document -when the source code is identified with begin and end markers. Working -with source code begins with identifying source code blocks. A source -code block can be placed almost anywhere in an Org document; it is not -restricted to the preamble or the end of the document. However, Org -cannot manage a source code block if it is placed inside an Org comment -or within a fixed width section. - - Here is an example source code block in the Emacs Lisp language: - - #+BEGIN_SRC emacs-lisp - (defun org-xor (a b) - "Exclusive or." - (if a (not b) b)) - #+END_SRC - - Source code blocks are one of many Org block types, which also -include “center”, “comment”, “dynamic”, “example”, “export”, “quote”, -“special”, and “verse”. This section pertains to blocks between -‘#+BEGIN_SRC’ and ‘#+END_SRC’. - - Details of Org’s facilities for working with source code are -described in the following sections. - -* Menu: - -* Features Overview:: Enjoy the versatility of source blocks. -* Structure of Code Blocks:: Code block syntax described. -* Using Header Arguments:: Different ways to set header arguments. -* Environment of a Code Block:: Arguments, sessions, working directory... -* Evaluating Code Blocks:: Place results of evaluation in the Org buffer. -* Results of Evaluation:: Choosing a results type, post-processing... -* Exporting Code Blocks:: Export contents and/or results. -* Extracting Source Code:: Create pure source code files. -* Languages:: List of supported code block languages. -* Editing Source Code:: Language major-mode editing. -* Noweb Reference Syntax:: Literate programming in Org mode. -* Library of Babel:: Use and contribute to a library of useful code blocks. -* Key bindings and Useful Functions:: Work quickly with code blocks. -* Batch Execution:: Call functions from the command line. - - -File: org.info, Node: Features Overview, Next: Structure of Code Blocks, Up: Working with Source Code - -16.1 Features Overview -====================== - -Org can manage the source code in the block delimited by ‘#+BEGIN_SRC’ -... ‘#+END_SRC’ in several ways that can simplify housekeeping tasks -essential to modern source code maintenance. Org can edit, format, -extract, export, and publish source code blocks. Org can also compile -and execute a source code block, then capture the results. The Org mode -literature sometimes refers to source code blocks as _live code_ blocks -because they can alter the content of the Org document or the material -that it exports. Users can control the “liveliness” of each source code -block by tweaking the header arguments (see *note Using Header -Arguments::) for compiling, execution, extraction, and exporting. - - For editing and formatting a source code block, Org uses an -appropriate Emacs major mode that includes features specifically -designed for source code in that language. - - Org can extract one or more source code blocks and write them to one -or more source files—a process known as _tangling_ in literate -programming terminology. - - For exporting and publishing, Org’s back-ends can format a source -code block appropriately, often with native syntax highlighting. - - For executing and compiling a source code block, the user can -configure Org to select the appropriate compiler. Org provides -facilities to collect the result of the execution or compiler output, -insert it into the Org document, and/or export it. In addition to text -results, Org can insert links to other data types, including audio, -video, and graphics. Org can also link a compiler error message to the -appropriate line in the source code block. - - An important feature of Org’s management of source code blocks is the -ability to pass variables, functions, and results to one another using a -common syntax for source code blocks in any language. Although most -literate programming facilities are restricted to one language or -another, Org’s language-agnostic approach lets the literate programmer -match each programming task with the appropriate computer language and -to mix them all together in a single Org document. This -interoperability among languages explains why Org’s source code -management facility was named _Org Babel_ by its originators, Eric -Schulte and Dan Davison. - - Org mode fulfills the promise of easy verification and maintenance of -publishing reproducible research by keeping text, data, code, -configuration settings of the execution environment, the results of the -execution, and associated narratives, claims, references, and internal -and external links in a single Org document. - - -File: org.info, Node: Structure of Code Blocks, Next: Using Header Arguments, Prev: Features Overview, Up: Working with Source Code - -16.2 Structure of Code Blocks -============================= - -Org offers two ways to structure source code in Org documents: in a -source code block, and directly inline. Both specifications are shown -below. - - A source code block conforms to this structure: - - #+NAME: <name> - #+BEGIN_SRC <language> <switches> <header arguments> - <body> - #+END_SRC - - Do not be put-off by having to remember the source block syntax. Org -mode offers a command for wrapping existing text in a block (see *note -Structure Templates::). Org also works with other completion systems in -Emacs, some of which predate Org and have custom domain-specific -languages for defining templates. Regular use of templates reduces -errors, increases accuracy, and maintains consistency. - - An inline code block conforms to this structure: - - src_<language>{<body>} - -or - - src_<language>[<header arguments>]{<body>} - -‘#+NAME: <name>’ - Optional. Names the source block so it can be called, like a - function, from other source blocks or inline code to evaluate or to - capture the results. Code from other blocks, other files, and from - table formulas (see *note The Spreadsheet::) can use the name to - reference a source block. This naming serves the same purpose as - naming Org tables. Org mode requires unique names. For duplicate - names, Org mode’s behavior is undefined. - -‘#+BEGIN_SRC’ ... ‘#+END_SRC’ - Mandatory. They mark the start and end of a block that Org - requires. The ‘#+BEGIN_SRC’ line takes additional arguments, as - described next. - -‘<language>’ - Mandatory. It is the identifier of the source code language in the - block. See *note Languages::, for identifiers of supported - languages. - -‘<switches>’ - Optional. Switches provide finer control of the code execution, - export, and format (see the discussion of switches in *note Literal - Examples::). - -‘<header arguments>’ - Optional. Heading arguments control many aspects of evaluation, - export and tangling of code blocks (see *note Using Header - Arguments::). Using Org’s properties feature, header arguments can - be selectively applied to the entire buffer or specific sub-trees - of the Org document. - -‘<body>’ - Source code in the dialect of the specified language identifier. - - -File: org.info, Node: Using Header Arguments, Next: Environment of a Code Block, Prev: Structure of Code Blocks, Up: Working with Source Code - -16.3 Using Header Arguments -=========================== - -Org comes with many header arguments common to all languages. New -header arguments are added for specific languages as they become -available for use in source code blocks. A header argument is specified -with an initial colon followed by the argument’s name in lowercase. - - Since header arguments can be set in several ways, Org prioritizes -them in case of overlaps or conflicts by giving local settings a higher -priority. Header values in function calls, for example, override header -values from global defaults. - -System-wide header arguments ----------------------------- - -System-wide values of header arguments can be specified by customizing -the ‘org-babel-default-header-args’ variable, which defaults to the -following values: - - :session => "none" - :results => "replace" - :exports => "code" - :cache => "no" - :noweb => "no" - - The example below sets ‘:noweb’ header arguments to ‘yes’, which -makes Org expand ‘:noweb’ references by default. - - (setq org-babel-default-header-args - (cons '(:noweb . "yes") - (assq-delete-all :noweb org-babel-default-header-args))) - - Each language can have separate default header arguments by -customizing the variable ‘org-babel-default-header-args:<LANG>’, where -<LANG> is the name of the language. For details, see the -language-specific online documentation at -<https://orgmode.org/worg/org-contrib/babel/>. - -Header arguments in Org mode properties ---------------------------------------- - -For header arguments applicable to the buffer, use ‘PROPERTY’ keyword -anywhere in the Org file (see *note Property Syntax::). - - The following example makes all the R code blocks execute in the same -session. Setting ‘:results’ to ‘silent’ ignores the results of -executions for all blocks, not just R code blocks; no results inserted -for any block. - - #+PROPERTY: header-args:R :session *R* - #+PROPERTY: header-args :results silent - - Header arguments set through Org’s property drawers (see *note -Property Syntax::) apply at the sub-tree level on down. Since these -property drawers can appear anywhere in the file hierarchy, Org uses -outermost call or source block to resolve the values. Org ignores -‘org-use-property-inheritance’ setting. - - In this example, ‘:cache’ defaults to ‘yes’ for all code blocks in -the sub-tree. - - * sample header - :PROPERTIES: - :header-args: :cache yes - :END: - - Properties defined through ‘org-set-property’ function, bound to ‘C-c -C-x p’, apply to all active languages. They override properties set in -‘org-babel-default-header-args’. - - Language-specific header arguments are also read from properties -‘header-args:<LANG>’ where <LANG> is the language identifier. For -example, - - * Heading - :PROPERTIES: - :header-args:clojure: :session *clojure-1* - :header-args:R: :session *R* - :END: - ** Subheading - :PROPERTIES: - :header-args:clojure: :session *clojure-2* - :END: - -would force separate sessions for Clojure blocks in ‘Heading’ and -‘Subheading’, but use the same session for all R blocks. Blocks in -‘Subheading’ inherit settings from ‘Heading’. - -Code block specific header arguments ------------------------------------- - -Header arguments are most commonly set at the source code block level, -on the ‘#+BEGIN_SRC’ line. Arguments set at this level take precedence -over those set in the ‘org-babel-default-header-args’ variable, and also -those set as header properties. - - In the following example, setting ‘:results’ to ‘silent’ makes it -ignore results of the code execution. Setting ‘:exports’ to ‘code’ -exports only the body of the code block to HTML or LaTeX. - - #+NAME: factorial - #+BEGIN_SRC haskell :results silent :exports code :var n=0 - fac 0 = 1 - fac n = n * fac (n-1) - #+END_SRC - - The same header arguments in an inline code block: - - src_haskell[:exports both]{fac 5} - - Code block header arguments can span multiple lines using ‘#+HEADER:’ -on each line. Note that Org currently accepts the plural spelling of -‘#+HEADER:’ only as a convenience for backward-compatibility. It may be -removed at some point. - - Multi-line header arguments on an unnamed code block: - - #+HEADER: :var data1=1 - #+BEGIN_SRC emacs-lisp :var data2=2 - (message "data1:%S, data2:%S" data1 data2) - #+END_SRC - - #+RESULTS: - : data1:1, data2:2 - - Multi-line header arguments on a named code block: - - #+NAME: named-block - #+HEADER: :var data=2 - #+BEGIN_SRC emacs-lisp - (message "data:%S" data) - #+END_SRC - - #+RESULTS: named-block - : data:2 - -Header arguments in function calls ----------------------------------- - -Header arguments in function calls are the most specific and override -all other settings in case of an overlap. They get the highest -priority. Two ‘#+CALL:’ examples are shown below. For the complete -syntax of ‘CALL’ keyword, see *note Evaluating Code Blocks::. - - In this example, ‘:exports results’ header argument is applied to the -evaluation of the ‘#+CALL:’ line. - - #+CALL: factorial(n=5) :exports results - - In this example, ‘:session special’ header argument is applied to the -evaluation of ‘factorial’ code block. - - #+CALL: factorial[:session special](n=5) - - -File: org.info, Node: Environment of a Code Block, Next: Evaluating Code Blocks, Prev: Using Header Arguments, Up: Working with Source Code - -16.4 Environment of a Code Block -================================ - -Passing arguments ------------------ - -Use ‘var’ for passing arguments to source code blocks. The specifics of -variables in code blocks vary by the source language and are covered in -the language-specific documentation. The syntax for ‘var’, however, is -the same for all languages. This includes declaring a variable, and -assigning a default value. - - The following syntax is used to pass arguments to code blocks using -the ‘var’ header argument. - - :var NAME=ASSIGN - -NAME is the name of the variable bound in the code block body. ASSIGN -is a literal value, such as a string, a number, a reference to a table, -a list, a literal example, another code block—with or without -arguments—or the results of evaluating a code block. ASSIGN may specify -a filename for references to elements in a different file, using a ‘:’ -to separate the filename from the reference. - - :var NAME=FILE:REFERENCE - - Here are examples of passing values by reference: - -table - A table named with a ‘NAME’ keyword. - - #+NAME: example-table - | 1 | - | 2 | - | 3 | - | 4 | - - #+NAME: table-length - #+BEGIN_SRC emacs-lisp :var table=example-table - (length table) - #+END_SRC - - #+RESULTS: table-length - : 4 - - When passing a table, you can treat specially the row, or the - column, containing labels for the columns, or the rows, in the - table. - - The ‘colnames’ header argument accepts ‘yes’, ‘no’, or ‘nil’ - values. The default value is ‘nil’: if an input table has column - names—because the second row is a horizontal rule—then Org removes - the column names, processes the table, puts back the column names, - and then writes the table to the results block. Using ‘yes’, Org - does the same to the first row, even if the initial table does not - contain any horizontal rule. When set to ‘no’, Org does not - pre-process column names at all. - - #+NAME: less-cols - | a | - |---| - | b | - | c | - - #+BEGIN_SRC python :var tab=less-cols :colnames nil - return [[val + '*' for val in row] for row in tab] - #+END_SRC - - #+RESULTS: - | a | - |----| - | b* | - | c* | - - Similarly, the ‘rownames’ header argument can take two values: - ‘yes’ or ‘no’. When set to ‘yes’, Org removes the first column, - processes the table, puts back the first column, and then writes - the table to the results block. The default is ‘no’, which means - Org does not pre-process the first column. Note that Emacs Lisp - code blocks ignore ‘rownames’ header argument because of the ease - of table-handling in Emacs. - - #+NAME: with-rownames - | one | 1 | 2 | 3 | 4 | 5 | - | two | 6 | 7 | 8 | 9 | 10 | - - #+BEGIN_SRC python :var tab=with-rownames :rownames yes - return [[val + 10 for val in row] for row in tab] - #+END_SRC - - #+RESULTS: - | one | 11 | 12 | 13 | 14 | 15 | - | two | 16 | 17 | 18 | 19 | 20 | - - To refer to a table in another file, join the filename and table name -with a colon, for example: ‘:var table=other-file.org:example-table’. - -list - A simple named list. - - #+NAME: example-list - - simple - - not - - nested - - list - - #+BEGIN_SRC emacs-lisp :var x=example-list - (print x) - #+END_SRC - - #+RESULTS: - | simple | list | - - Note that only the top level list items are passed along. Nested - list items are ignored. - -code block without arguments - A code block name, as assigned by ‘NAME’ keyword from the example - above, optionally followed by parentheses. - - #+BEGIN_SRC emacs-lisp :var length=table-length() - (* 2 length) - #+END_SRC - - #+RESULTS: - : 8 - -code block with arguments - A code block name, as assigned by ‘NAME’ keyword, followed by - parentheses and optional arguments passed within the parentheses. - - #+NAME: double - #+BEGIN_SRC emacs-lisp :var input=8 - (* 2 input) - #+END_SRC - - #+RESULTS: double - : 16 - - #+NAME: squared - #+BEGIN_SRC emacs-lisp :var input=double(input=1) - (* input input) - #+END_SRC - - #+RESULTS: squared - : 4 - -literal example - A literal example block named with a ‘NAME’ keyword. - - #+NAME: literal-example - #+BEGIN_EXAMPLE - A literal example - on two lines - #+END_EXAMPLE - - #+NAME: read-literal-example - #+BEGIN_SRC emacs-lisp :var x=literal-example - (concatenate #'string x " for you.") - #+END_SRC - - #+RESULTS: read-literal-example - : A literal example - : on two lines for you. - - Indexing variable values enables referencing portions of a variable. -Indexes are 0 based with negative values counting backwards from the -end. If an index is separated by commas then each subsequent section -indexes as the next dimension. Note that this indexing occurs _before_ -other table-related header arguments are applied, such as ‘hlines’, -‘colnames’ and ‘rownames’. The following example assigns the last cell -of the first row the table ‘example-table’ to the variable ‘data’: - - #+NAME: example-table - | 1 | a | - | 2 | b | - | 3 | c | - | 4 | d | - - #+BEGIN_SRC emacs-lisp :var data=example-table[0,-1] - data - #+END_SRC - - #+RESULTS: - : a - - Two integers separated by a colon reference a range of variable -values. In that case the entire inclusive range is referenced. For -example the following assigns the middle three rows of ‘example-table’ -to ‘data’. - - #+NAME: example-table - | 1 | a | - | 2 | b | - | 3 | c | - | 4 | d | - | 5 | 3 | - - #+BEGIN_SRC emacs-lisp :var data=example-table[1:3] - data - #+END_SRC - - #+RESULTS: - | 2 | b | - | 3 | c | - | 4 | d | - - To pick the entire range, use an empty index, or the single character -‘*’. ‘0:-1’ does the same thing. Example below shows how to reference -the first column only. - - #+NAME: example-table - | 1 | a | - | 2 | b | - | 3 | c | - | 4 | d | - - #+BEGIN_SRC emacs-lisp :var data=example-table[,0] - data - #+END_SRC - - #+RESULTS: - | 1 | 2 | 3 | 4 | - - Index referencing can be used for tables and code blocks. Index -referencing can handle any number of dimensions. Commas delimit -multiple dimensions, as shown below. - - #+NAME: 3D - #+BEGIN_SRC emacs-lisp - '(((1 2 3) (4 5 6) (7 8 9)) - ((10 11 12) (13 14 15) (16 17 18)) - ((19 20 21) (22 23 24) (25 26 27))) - #+END_SRC - - #+BEGIN_SRC emacs-lisp :var data=3D[1,,1] - data - #+END_SRC - - #+RESULTS: - | 11 | 14 | 17 | - - Note that row names and column names are not removed prior to -variable indexing. You need to take them into account, even when -‘colnames’ or ‘rownames’ header arguments remove them. - - Emacs lisp code can also set the values for variables. To -differentiate a value from Lisp code, Org interprets any value starting -with ‘(’, ‘[’, ‘'’ or ‘`’ as Emacs Lisp code. The result of evaluating -that code is then assigned to the value of that variable. The following -example shows how to reliably query and pass the file name of the Org -mode buffer to a code block using headers. We need reliability here -because the file’s name could change once the code in the block starts -executing. - - #+BEGIN_SRC sh :var filename=(buffer-file-name) :exports both - wc -w $filename - #+END_SRC - - Note that values read from tables and lists are not mistakenly -evaluated as Emacs Lisp code, as illustrated in the following example. - - #+NAME: table - | (a b c) | - - #+HEADER: :var data=table[0,0] - #+BEGIN_SRC perl - $data - #+END_SRC - - #+RESULTS: - : (a b c) - -Using sessions --------------- - -Two code blocks can share the same environment. The ‘session’ header -argument is for running multiple source code blocks under one session. -Org runs code blocks with the same session name in the same interpreter -process. - -‘none’ - Default. Each code block gets a new interpreter process to - execute. The process terminates once the block is evaluated. - -STRING - Any string besides ‘none’ turns that string into the name of that - session. For example, ‘:session STRING’ names it ‘STRING’. If - ‘session’ has no value, then the session name is derived from the - source language identifier. Subsequent blocks with the same source - code language use the same session. Depending on the language, - state variables, code from other blocks, and the overall - interpreted environment may be shared. Some interpreted languages - support concurrent sessions when subsequent source code language - blocks change session names. - - Only languages that provide interactive evaluation can have session -support. Not all languages provide this support, such as C and ditaa. -Even languages, such as Python and Haskell, that do support interactive -evaluation impose limitations on allowable language constructs that can -run interactively. Org inherits those limitations for those code blocks -running in a session. - -Choosing a working directory ----------------------------- - -The ‘dir’ header argument specifies the default directory during code -block execution. If it is absent, then the directory associated with -the current buffer is used. In other words, supplying ‘:dir DIRECTORY’ -temporarily has the same effect as changing the current directory with -‘M-x cd <RET> DIRECTORY’, and then not setting ‘dir’. Under the -surface, ‘dir’ simply sets the value of the Emacs variable -‘default-directory’. Setting ‘mkdirp’ header argument to a non-‘nil’ -value creates the directory, if necessary. - - For example, to save the plot file in the ‘Work/’ folder of the home -directory—notice tilde is expanded: - - #+BEGIN_SRC R :file myplot.png :dir ~/Work - matplot(matrix(rnorm(100), 10), type="l") - #+END_SRC - - To evaluate the code block on a remote machine, supply a remote -directory name using Tramp syntax. For example: - - #+BEGIN_SRC R :file plot.png :dir /scp:dand@yakuba.princeton.edu: - plot(1:10, main=system("hostname", intern=TRUE)) - #+END_SRC - - Org first captures the text results as usual for insertion in the Org -file. Then Org also inserts a link to the remote file, thanks to Emacs -Tramp. Org constructs the remote path to the file name from ‘dir’ and -‘default-directory’, as illustrated here: - - [[file:/scp:dand@yakuba.princeton.edu:/home/dand/plot.png][plot.png]] - - When ‘dir’ is used with ‘session’, Org sets the starting directory -for a new session. But Org does not alter the directory of an already -existing session. - - Do not use ‘dir’ with ‘:exports results’ or with ‘:exports both’ to -avoid Org inserting incorrect links to remote files. That is because -Org does not expand ‘default directory’ to avoid some underlying -portability issues. - -Inserting headers and footers ------------------------------ - -The ‘prologue’ header argument is for appending to the top of the code -block for execution, like a reset instruction. For example, you may use -‘:prologue "reset"’ in a Gnuplot code block or, for every such block: - - (add-to-list 'org-babel-default-header-args:gnuplot - '((:prologue . "reset"))) - - - Likewise, the value of the ‘epilogue’ header argument is for -appending to the end of the code block for execution. - - -File: org.info, Node: Evaluating Code Blocks, Next: Results of Evaluation, Prev: Environment of a Code Block, Up: Working with Source Code - -16.5 Evaluating Code Blocks -=========================== - -A note about security: With code evaluation comes the risk of harm. Org -safeguards by prompting for user’s permission before executing any code -in the source block. To customize this safeguard, or disable it, see -*note Code Evaluation Security::. - -How to evaluate source code ---------------------------- - -Org captures the results of the code block evaluation and inserts them -in the Org file, right after the code block. The insertion point is -after a newline and the ‘RESULTS’ keyword. Org creates the ‘RESULTS’ -keyword if one is not already there. - - By default, Org enables only Emacs Lisp code blocks for execution. -See *note Languages:: to enable other languages. - - Org provides many ways to execute code blocks. ‘C-c C-c’ or ‘C-c C-v -e’ with the point on a code block(1) calls the -‘org-babel-execute-src-block’ function, which executes the code in the -block, collects the results, and inserts them in the buffer. - - By calling a named code block(2) from an Org mode buffer or a table. -Org can call the named code blocks from the current Org mode buffer or -from the “Library of Babel” (see *note Library of Babel::). - - The syntax for ‘CALL’ keyword is: - - #+CALL: <name>(<arguments>) - #+CALL: <name>[<inside header arguments>](<arguments>) <end header arguments> - - The syntax for inline named code blocks is: - - ... call_<name>(<arguments>) ... - ... call_<name>[<inside header arguments>](<arguments>)[<end header arguments>] ... - - When inline syntax is used, the result is wrapped based on the -variable ‘org-babel-inline-result-wrap’, which by default is set to -‘"=%s="’ to produce verbatim text suitable for markup. - -‘<name>’ - This is the name of the code block (see *note Structure of Code - Blocks::) to be evaluated in the current document. If the block is - located in another file, start ‘<name>’ with the file name followed - by a colon. For example, in order to execute a block named - ‘clear-data’ in ‘file.org’, you can write the following: - - #+CALL: file.org:clear-data() - -‘<arguments>’ - Org passes arguments to the code block using standard function call - syntax. For example, a ‘#+CALL:’ line that passes ‘4’ to a code - block named ‘double’, which declares the header argument ‘:var - n=2’, would be written as: - - #+CALL: double(n=4) - - Note how this function call syntax is different from the header - argument syntax. - -‘<inside header arguments>’ - Org passes inside header arguments to the named code block using - the header argument syntax. Inside header arguments apply to code - block evaluation. For example, ‘[:results output]’ collects - results printed to stdout during code execution of that block. - Note how this header argument syntax is different from the function - call syntax. - -‘<end header arguments>’ - End header arguments affect the results returned by the code block. - For example, ‘:results html’ wraps the results in a ‘#+BEGIN_EXPORT - html’ block before inserting the results in the Org buffer. - -Limit code block evaluation ---------------------------- - -The ‘eval’ header argument can limit evaluation of specific code blocks -and ‘CALL’ keyword. It is useful for protection against evaluating -untrusted code blocks by prompting for a confirmation. - -‘never’ or ‘no’ - Org never evaluates the source code. - -‘query’ - Org prompts the user for permission to evaluate the source code. - -‘never-export’ or ‘no-export’ - Org does not evaluate the source code when exporting, yet the user - can evaluate it interactively. - -‘query-export’ - Org prompts the user for permission to evaluate the source code - during export. - - If ‘eval’ header argument is not set, then Org determines whether to -evaluate the source code from the ‘org-confirm-babel-evaluate’ variable -(see *note Code Evaluation Security::). - -Cache results of evaluation ---------------------------- - -The ‘cache’ header argument is for caching results of evaluating code -blocks. Caching results can avoid re-evaluating a code block that have -not changed since the previous run. To benefit from the cache and avoid -redundant evaluations, the source block must have a result already -present in the buffer, and neither the header arguments—including the -value of ‘var’ references—nor the text of the block itself has changed -since the result was last computed. This feature greatly helps avoid -long-running calculations. For some edge cases, however, the cached -results may not be reliable. - - The caching feature is best for when code blocks are pure functions, -that is functions that return the same value for the same input -arguments (see *note Environment of a Code Block::), and that do not -have side effects, and do not rely on external variables other than the -input arguments. Functions that depend on a timer, file system objects, -and random number generators are clearly unsuitable for caching. - - A note of warning: when ‘cache’ is used in a session, caching may -cause unexpected results. - - When the caching mechanism tests for any source code changes, it does -not expand noweb style references (see *note Noweb Reference Syntax::). - - The ‘cache’ header argument can have one of two values: ‘yes’ or -‘no’. - -‘no’ - Default. No caching of results; code block evaluated every time. - -‘yes’ - Whether to run the code or return the cached results is determined - by comparing the SHA1 hash value of the combined code block and - arguments passed to it. This hash value is packed on the - ‘#+RESULTS:’ line from previous evaluation. When hash values - match, Org does not evaluate the code block. When hash values - mismatch, Org evaluates the code block, inserts the results, - recalculates the hash value, and updates ‘#+RESULTS:’ line. - - In this example, both functions are cached. But ‘caller’ runs only -if the result from ‘random’ has changed since the last run. - - #+NAME: random - #+BEGIN_SRC R :cache yes - runif(1) - #+END_SRC - - #+RESULTS[a2a72cd647ad44515fab62e144796432793d68e1]: random - 0.4659510825295 - - #+NAME: caller - #+BEGIN_SRC emacs-lisp :var x=random :cache yes - x - #+END_SRC - - #+RESULTS[bec9c8724e397d5df3b696502df3ed7892fc4f5f]: caller - 0.254227238707244 - - ---------- Footnotes ---------- - - (1) The option ‘org-babel-no-eval-on-ctrl-c-ctrl-c’ can be used to -remove code evaluation from the ‘C-c C-c’ key binding. - - (2) Actually, the constructs ‘call_<name>()’ and ‘src_<lang>{}’ are -not evaluated when they appear in a keyword (see *note In-buffer -Settings::). - - -File: org.info, Node: Results of Evaluation, Next: Exporting Code Blocks, Prev: Evaluating Code Blocks, Up: Working with Source Code - -16.6 Results of Evaluation -========================== - -How Org handles results of a code block execution depends on many header -arguments working together. The primary determinant, however, is the -‘results’ header argument. It accepts four classes of options. Each -code block can take only one option per class: - -Collection - For how the results should be collected from the code block; - -Type - For which type of result the code block will return; affects how - Org processes and inserts results in the Org buffer; - -Format - For the result; affects how Org processes results; - -Handling - For inserting results once they are properly formatted. - -Collection ----------- - -Collection options specify the results. Choose one of the options; they -are mutually exclusive. - -‘value’ - Default for most Babel libraries(1). Functional mode. Org gets - the value by wrapping the code in a function definition in the - language of the source block. That is why when using ‘:results - value’, code should execute like a function and return a value. - For languages like Python, an explicit ‘return’ statement is - mandatory when using ‘:results value’. Result is the value - returned by the last statement in the code block. - - When evaluating the code block in a session (see *note Environment - of a Code Block::), Org passes the code to an interpreter running - as an interactive Emacs inferior process. Org gets the value from - the source code interpreter’s last statement output. Org has to - use language-specific methods to obtain the value. For example, - from the variable ‘_’ in Ruby, and the value of ‘.Last.value’ in R. - -‘output’ - Scripting mode. Org passes the code to an external process running - the interpreter. Org returns the contents of the standard output - stream as text results. - - When using a session, Org passes the code to the interpreter - running as an interactive Emacs inferior process. Org concatenates - any text output from the interpreter and returns the collection as - a result. - -Type ----- - -Type tells what result types to expect from the execution of the code -block. Choose one of the options; they are mutually exclusive. The -default behavior is to automatically determine the result type. - -‘table’ -‘vector’ - Interpret the results as an Org table. If the result is a single - value, create a table with one row and one column. Usage example: - ‘:results value table’. - - In-between each table row or below the table headings, sometimes - results have horizontal lines, which are also known as “hlines”. - The ‘hlines’ argument with the default ‘no’ value strips such lines - from the input table. For most code, this is desirable, or else - those ‘hline’ symbols raise unbound variable errors. A ‘yes’ - accepts such lines, as demonstrated in the following example. - - #+NAME: many-cols - | a | b | c | - |---+---+---| - | d | e | f | - |---+---+---| - | g | h | i | - - #+NAME: no-hline - #+BEGIN_SRC python :var tab=many-cols :hlines no - return tab - #+END_SRC - - #+RESULTS: no-hline - | a | b | c | - | d | e | f | - | g | h | i | - - #+NAME: hlines - #+BEGIN_SRC python :var tab=many-cols :hlines yes - return tab - #+END_SRC - - #+RESULTS: hlines - | a | b | c | - |---+---+---| - | d | e | f | - |---+---+---| - | g | h | i | - -‘list’ - Interpret the results as an Org list. If the result is a single - value, create a list of one element. - -‘scalar’ -‘verbatim’ - Interpret literally and insert as quoted text. Do not create a - table. Usage example: ‘:results value verbatim’. - -‘file’ - Interpret as a filename. Save the results of execution of the code - block to that file, then insert a link to it. You can control both - the filename and the description associated to the link. - - Org first tries to generate the filename from the value of the - ‘file’ header argument and the directory specified using the - ‘output-dir’ header arguments. If ‘output-dir’ is not specified, - Org assumes it is the current directory. - - #+BEGIN_SRC asymptote :results value file :file circle.pdf :output-dir img/ - size(2cm); - draw(unitcircle); - #+END_SRC - - If ‘file’ header argument is missing, Org generates the base name - of the output file from the name of the code block, and its - extension from the ‘file-ext’ header argument. In that case, both - the name and the extension are mandatory. - - #+name: circle - #+BEGIN_SRC asymptote :results value file :file-ext pdf - size(2cm); - draw(unitcircle); - #+END_SRC - - The ‘file-desc’ header argument defines the description (see *note - Link Format::) for the link. If ‘file-desc’ is present but has no - value, the ‘file’ value is used as the link description. When this - argument is not present, the description is omitted. If you want - to provide the ‘file-desc’ argument but omit the description, you - can provide it with an empty vector (i.e., :file-desc []). - - By default, Org assumes that a table written to a file has - TAB-delimited output. You can choose a different separator with - the ‘sep’ header argument. - - The ‘file-mode’ header argument defines the file permissions. To - make it executable, use ‘:file-mode (identity #o755)’. - - #+BEGIN_SRC shell :results file :file script.sh :file-mode (identity #o755) - echo "#!/bin/bash" - echo "echo Hello World" - #+END_SRC - -Format ------- - -Format pertains to the type of the result returned by the code block. -Choose one of the options; they are mutually exclusive. The default -follows from the type specified above. - -‘code’ - Result enclosed in a code block. Useful for parsing. Usage - example: ‘:results value code’. - -‘drawer’ - Result wrapped in a ‘RESULTS’ drawer. Useful for containing ‘raw’ - or ‘org’ results for later scripting and automated processing. - Usage example: ‘:results value drawer’. - -‘html’ - Results enclosed in a ‘BEGIN_EXPORT html’ block. Usage example: - ‘:results value html’. - -‘latex’ - Results enclosed in a ‘BEGIN_EXPORT latex’ block. Usage example: - ‘:results value latex’. - -‘link’ -‘graphics’ - When used along with ‘file’ type, the result is a link to the file - specified in ‘:file’ header argument. However, unlike plain ‘file’ - type, nothing is written to the disk. The block is used for its - side-effects only, as in the following example: - - #+begin_src shell :results file link :file "download.tar.gz" - wget -c "https://example.com/download.tar.gz" - #+end_src - -‘org’ - Results enclosed in a ‘BEGIN_SRC org’ block. For comma-escape, - either ‘<TAB>’ in the block, or export the file. Usage example: - ‘:results value org’. - -‘pp’ - Result converted to pretty-print source code. Enclosed in a code - block. Languages supported: Emacs Lisp, Python, and Ruby. Usage - example: ‘:results value pp’. - -‘raw’ - Interpreted as raw Org mode. Inserted directly into the buffer. - Aligned if it is a table. Usage example: ‘:results value raw’. - - The ‘wrap’ header argument unconditionally marks the results block by -appending strings to ‘#+BEGIN_’ and ‘#+END_’. If no string is -specified, Org wraps the results in a ‘#+BEGIN_results’ ... -‘#+END_results’ block. It takes precedent over the ‘results’ value -listed above. E.g., - - #+BEGIN_SRC emacs-lisp :results html :wrap EXPORT markdown - "<blink>Welcome back to the 90's</blink>" - #+END_SRC - - #+RESULTS: - #+BEGIN_EXPORT markdown - <blink>Welcome back to the 90's</blink> - #+END_EXPORT - -Handling --------- - -Handling options after collecting the results. - -‘replace’ - Default. Insert results in the Org buffer. Remove previous - results. Usage example: ‘:results output replace’. - -‘silent’ - Do not insert results in the Org mode buffer, but echo them in the - minibuffer. Usage example: ‘:results output silent’. - -‘none’ - Do not process results at all. No inserting in the Org mode buffer - nor echo them in the minibuffer. Usage example: ‘:results none’. - -‘append’ - Append results to the Org buffer. Latest results are at the - bottom. Does not remove previous results. Usage example: - ‘:results output append’. - -‘prepend’ - Prepend results to the Org buffer. Latest results are at the top. - Does not remove previous results. Usage example: ‘:results output - prepend’. - -Post-processing ---------------- - -The ‘post’ header argument is for post-processing results from block -evaluation. When ‘post’ has any value, Org binds the results to -‘*this*’ variable for easy passing to ‘var’ header argument -specifications (see *note Environment of a Code Block::). That makes -results available to other code blocks, or even for direct Emacs Lisp -code execution. - - The following two examples illustrate ‘post’ header argument in -action. The first one shows how to attach an ‘ATTR_LATEX’ keyword using -‘post’. - - #+NAME: attr_wrap - #+BEGIN_SRC sh :var data="" :var width="\\textwidth" :results output - echo "#+ATTR_LATEX: :width $width" - echo "$data" - #+END_SRC - - #+HEADER: :file /tmp/it.png - #+BEGIN_SRC dot :post attr_wrap(width="5cm", data=*this*) :results drawer - digraph{ - a -> b; - b -> c; - c -> a; - } - #+end_src - - #+RESULTS: - :RESULTS: - #+ATTR_LATEX :width 5cm - [[file:/tmp/it.png]] - :END: - - The second example shows use of ‘colnames’ header argument in ‘post’ -to pass data between code blocks. - - #+NAME: round-tbl - #+BEGIN_SRC emacs-lisp :var tbl="" fmt="%.3f" - (mapcar (lambda (row) - (mapcar (lambda (cell) - (if (numberp cell) - (format fmt cell) - cell)) - row)) - tbl) - #+end_src - - #+BEGIN_SRC R :colnames yes :post round-tbl[:colnames yes](*this*) - set.seed(42) - data.frame(foo=rnorm(1)) - #+END_SRC - - #+RESULTS: - | foo | - |-------| - | 1.371 | - - ---------- Footnotes ---------- - - (1) Actually, the constructs ‘call_<name>()’ and ‘src_<lang>{}’ are -not evaluated when they appear in a keyword (see *note In-buffer -Settings::). - - -File: org.info, Node: Exporting Code Blocks, Next: Extracting Source Code, Prev: Results of Evaluation, Up: Working with Source Code - -16.7 Exporting Code Blocks -========================== - -It is possible to export the _code_ of code blocks, the _results_ of -code block evaluation, _both_ the code and the results of code block -evaluation, or _none_. Org defaults to exporting _code_ for most -languages. For some languages, such as ditaa, Org defaults to -_results_. To export just the body of code blocks, see *note Literal -Examples::. To selectively export sub-trees of an Org document, see -*note Exporting::. - - The ‘exports’ header argument is to specify if that part of the Org -file is exported to, say, HTML or LaTeX formats. - -‘code’ - The default. The body of code is included into the exported file. - Example: ‘:exports code’. - -‘results’ - The results of evaluation of the code is included in the exported - file. Example: ‘:exports results’. - -‘both’ - Both the code and results of evaluation are included in the - exported file. Example: ‘:exports both’. - -‘none’ - Neither the code nor the results of evaluation is included in the - exported file. Whether the code is evaluated at all depends on - other options. Example: ‘:exports none’. - - To stop Org from evaluating code blocks to speed exports, use the -header argument ‘:eval never-export’ (see *note Evaluating Code -Blocks::). To stop Org from evaluating code blocks for greater -security, set the ‘org-export-use-babel’ variable to ‘nil’, but -understand that header arguments will have no effect. - - Turning off evaluation comes in handy when batch processing. For -example, markup languages for wikis, which have a high risk of untrusted -code. Stopping code block evaluation also stops evaluation of all -header arguments of the code block. This may not be desirable in some -circumstances. So during export, to allow evaluation of just the header -arguments but not any code evaluation in the source block, set ‘:eval -never-export’ (see *note Evaluating Code Blocks::). - - Org never evaluates code blocks in commented sub-trees when exporting -(see *note Comment Lines::). On the other hand, Org does evaluate code -blocks in sub-trees excluded from export (see *note Export Settings::). - - -File: org.info, Node: Extracting Source Code, Next: Languages, Prev: Exporting Code Blocks, Up: Working with Source Code - -16.8 Extracting Source Code -=========================== - -Extracting source code from code blocks is a basic task in literate -programming. Org has features to make this easy. In literate -programming parlance, documents on creation are _woven_ with code and -documentation, and on export, the code is tangled for execution by a -computer. Org facilitates weaving and tangling for producing, -maintaining, sharing, and exporting literate programming documents. Org -provides extensive customization options for extracting source code. - - When Org tangles code blocks, it expands, merges, and transforms -them. Then Org recomposes them into one or more separate files, as -configured through the options. During this tangling process, Org -expands variables in the source code, and resolves any noweb style -references (see *note Noweb Reference Syntax::). - -Header arguments ----------------- - -The ‘tangle’ header argument specifies if the code block is exported to -source file(s). - -‘yes’ - Export the code block to source file. The file name for the source - file is derived from the name of the Org file, and the file - extension is derived from the source code language identifier. - Example: ‘:tangle yes’. - -‘no’ - The default. Do not extract the code in a source code file. - Example: ‘:tangle no’. - -FILENAME - Export the code block to source file whose file name is derived - from any string passed to the ‘tangle’ header argument. Org - derives the file name as being relative to the directory of the Org - file’s location. Example: ‘:tangle FILENAME’. - - The ‘mkdirp’ header argument creates parent directories for tangled -files if the directory does not exist. A ‘yes’ value enables directory -creation whereas ‘no’ inhibits it. - - The ‘comments’ header argument controls inserting comments into -tangled files. These are above and beyond whatever comments may already -exist in the code block. - -‘no’ - The default. Do not insert any extra comments during tangling. - -‘link’ - Wrap the code block in comments. Include links pointing back to - the place in the Org file from where the code was tangled. - -‘yes’ - Kept for backward compatibility; same as ‘link’. - -‘org’ - Nearest headline text from Org file is inserted as comment. The - exact text that is inserted is picked from the leading context of - the source block. - -‘both’ - Includes both ‘link’ and ‘org’ options. - -‘noweb’ - Includes ‘link’ option, expands noweb references (see *note Noweb - Reference Syntax::), and wraps them in link comments inside the - body of the code block. - - The ‘padline’ header argument controls insertion of newlines to pad -source code in the tangled file. - -‘yes’ - Default. Insert a newline before and after each code block in the - tangled file. - -‘no’ - Do not insert newlines to pad the tangled code blocks. - - The ‘shebang’ header argument can turn results into executable script -files. By setting it to a string value—for example, ‘:shebang -"#!/bin/bash"’—Org inserts that string as the first line of the tangled -file that the code block is extracted to. Org then turns on the tangled -file’s executable permission. - - The ‘tangle-mode’ header argument specifies what permissions to set -for tangled files by ‘set-file-modes’. For example, to make a read-only -tangled file, use ‘:tangle-mode (identity #o444)’. To make it -executable, use ‘:tangle-mode (identity #o755)’. It also overrides -executable permission granted by ‘shebang’. When multiple source code -blocks tangle to a single file with different and conflicting -‘tangle-mode’ header arguments, Org’s behavior is undefined. - - By default Org expands code blocks during tangling. The ‘no-expand’ -header argument turns off such expansions. Note that one side-effect of -expansion by ‘org-babel-expand-src-block’ also assigns values (see *note -Environment of a Code Block::) to variables. Expansions also replace -noweb references with their targets (see *note Noweb Reference -Syntax::). Some of these expansions may cause premature assignment, -hence this option. This option makes a difference only for tangling. -It has no effect when exporting since code blocks for execution have to -be expanded anyway. - -Functions ---------- - -‘org-babel-tangle’ - Tangle the current file. Bound to ‘C-c C-v t’. - - With prefix argument only tangle the current code block. - -‘org-babel-tangle-file’ - Choose a file to tangle. Bound to ‘C-c C-v f’. - -Tangle hooks ------------- - -‘org-babel-post-tangle-hook’ - This hook is run from within code files tangled by - ‘org-babel-tangle’, making it suitable for post-processing, - compilation, and evaluation of code in the tangled files. - -Jumping between code and Org ----------------------------- - -Debuggers normally link errors and messages back to the source code. -But for tangled files, we want to link back to the Org file, not to the -tangled source file. To make this extra jump, Org uses -‘org-babel-tangle-jump-to-org’ function with two additional source code -block header arguments: - - 1. Set ‘padline’ to true—this is the default setting. - 2. Set ‘comments’ to ‘link’, which makes Org insert links to the Org - file. - - -File: org.info, Node: Languages, Next: Editing Source Code, Prev: Extracting Source Code, Up: Working with Source Code - -16.9 Languages -============== - -Code blocks in dozens of languages are supported. See Worg for language -specific documentation -(https://orgmode.org/worg/org-contrib/babel/languages/index.html). - - By default, only Emacs Lisp is enabled for evaluation. To enable or -disable other languages, customize the ‘org-babel-load-languages’ -variable either through the Emacs customization interface, or by adding -code to the init file as shown next. - - In this example, evaluation is disabled for Emacs Lisp, and enabled -for R. - - (org-babel-do-load-languages - 'org-babel-load-languages - '((emacs-lisp . nil) - (R . t))) - - Note that this is not the only way to enable a language. Org also -enables languages when loaded with ‘require’ statement. For example, -the following enables execution of Clojure code blocks: - - (require 'ob-clojure) - - -File: org.info, Node: Editing Source Code, Next: Noweb Reference Syntax, Prev: Languages, Up: Working with Source Code - -16.10 Editing Source Code -========================= - -Use ‘C-c '’ to edit the current code block. It opens a new major mode -edit buffer containing the body of the source code block, ready for any -edits. Use ‘C-c '’ again to close the buffer and return to the Org -buffer. - - ‘C-x C-s’ saves the buffer and updates the contents of the Org -buffer. Set ‘org-edit-src-auto-save-idle-delay’ to save the base buffer -after a certain idle delay time. Set ‘org-edit-src-turn-on-auto-save’ -to auto-save this buffer into a separate file using Auto-save mode. - - While editing the source code in the major mode, the Org Src minor -mode remains active. It provides these customization variables as -described below. For even more variables, look in the customization -group ‘org-edit-structure’. - -‘org-src-lang-modes’ - If an Emacs major-mode named ‘<LANG>-mode’ exists, where <LANG> is - the language identifier from code block’s header line, then the - edit buffer uses that major mode. Use this variable to arbitrarily - map language identifiers to major modes. - -‘org-src-window-setup’ - For specifying Emacs window arrangement when the new edit buffer is - created. - -‘org-src-preserve-indentation’ - Default is ‘nil’. Source code is indented. This indentation - applies during export or tangling, and depending on the context, - may alter leading spaces and tabs. When non-‘nil’, source code is - aligned with the leftmost column. No lines are modified during - export or tangling, which is very useful for white-space sensitive - languages, such as Python. - -‘org-src-ask-before-returning-to-edit-buffer’ - When ‘nil’, Org returns to the edit buffer without further prompts. - The default prompts for a confirmation. - - Set ‘org-src-fontify-natively’ to non-‘nil’ to turn on native code -fontification in the _Org_ buffer. Fontification of code blocks can -give visual separation of text and code on the display page. To further -customize the appearance of ‘org-block’ for specific languages, -customize ‘org-src-block-faces’. The following example shades the -background of regular blocks, and colors source blocks only for Python -and Emacs Lisp languages. - - (require 'color) - (set-face-attribute 'org-block nil :background - (color-darken-name - (face-attribute 'default :background) 3)) - - (setq org-src-block-faces '(("emacs-lisp" (:background "#EEE2FF")) - ("python" (:background "#E5FFB8")))) - - -File: org.info, Node: Noweb Reference Syntax, Next: Library of Babel, Prev: Editing Source Code, Up: Working with Source Code - -16.11 Noweb Reference Syntax -============================ - -Source code blocks can include references to other source code blocks, -using a noweb(1) style syntax: - - <<CODE-BLOCK-ID>> - -where CODE-BLOCK-ID refers to either the ‘NAME’ of a single source code -block, or a collection of one or more source code blocks sharing the -same ‘noweb-ref’ header argument (see *note Using Header Arguments::). -Org can replace such references with the source code of the block or -blocks being referenced, or, in the case of a single source code block -named with ‘NAME’, with the results of an evaluation of that block. - - The ‘noweb’ header argument controls expansion of noweb syntax -references. Expansions occur when source code blocks are evaluated, -tangled, or exported. - -‘no’ - Default. No expansion of noweb syntax references in the body of - the code when evaluating, tangling, or exporting. - -‘yes’ - Expansion of noweb syntax references in the body of the code block - when evaluating, tangling, or exporting. - -‘tangle’ - Expansion of noweb syntax references in the body of the code block - when tangling. No expansion when evaluating or exporting. - -‘no-export’ - Expansion of noweb syntax references in the body of the code block - when evaluating or tangling. No expansion when exporting. - -‘strip-export’ - Expansion of noweb syntax references in the body of the code block - when expanding prior to evaluating or tangling. Removes noweb - syntax references when exporting. - -‘eval’ - Expansion of noweb syntax references in the body of the code block - only before evaluating. - - In the most simple case, the contents of a single source block is -inserted within other blocks. Thus, in following example, - - #+NAME: initialization - #+BEGIN_SRC emacs-lisp - (setq sentence "Never a foot too far, even.") - #+END_SRC - - #+BEGIN_SRC emacs-lisp :noweb yes - <<initialization>> - (reverse sentence) - #+END_SRC - -the second code block is expanded as - - #+BEGIN_SRC emacs-lisp :noweb yes - (setq sentence "Never a foot too far, even.") - (reverse sentence) - #+END_SRC - - You may also include the contents of multiple blocks sharing a common -‘noweb-ref’ header argument, which can be set at the file, sub-tree, or -code block level. In the example Org file shown next, the body of the -source code in each block is extracted for concatenation to a pure code -file when tangled. - - #+BEGIN_SRC sh :tangle yes :noweb yes :shebang #!/bin/sh - <<fullest-disk>> - #+END_SRC - * the mount point of the fullest disk - :PROPERTIES: - :header-args: :noweb-ref fullest-disk - :END: - - ** query all mounted disks - #+BEGIN_SRC sh - df \ - #+END_SRC - - ** strip the header row - #+BEGIN_SRC sh - |sed '1d' \ - #+END_SRC - - ** output mount point of fullest disk - #+BEGIN_SRC sh - |awk '{if (u < +$5) {u = +$5; m = $6}} END {print m}' - #+END_SRC - - By default a newline separates each noweb reference concatenation. -To use a different separator, edit the ‘noweb-sep’ header argument. - - Alternatively, Org can include the results of evaluation of a single -code block rather than its body. Evaluation occurs when parentheses, -possibly including arguments, are appended to the code block name, as -shown below. - - <<NAME(optional arguments)>> - - Note that in this case, a code block name set by ‘NAME’ keyword is -required; the reference set by ‘noweb-ref’ will not work when evaluation -is desired. - - Here is an example that demonstrates how the exported content changes -when noweb style references are used with parentheses versus without. -Given: - - #+NAME: some-code - #+BEGIN_SRC python :var num=0 :results output :exports none - print(num*10) - #+END_SRC - -this code block: - - #+BEGIN_SRC text :noweb yes - <<some-code>> - #+END_SRC - -expands to: - - print(num*10) - - Below, a similar noweb style reference is used, but with parentheses, -while setting a variable ‘num’ to 10: - - #+BEGIN_SRC text :noweb yes - <<some-code(num=10)>> - #+END_SRC - -Note that the expansion now contains the results of the code block -‘some-code’, not the code block itself: - - 100 - - Noweb insertions honor prefix characters that appear before the noweb -syntax reference. This behavior is illustrated in the following -example. Because the ‘<<example>>’ noweb reference appears behind the -SQL comment syntax, each line of the expanded noweb reference is -commented. With: - - #+NAME: example - #+BEGIN_SRC text - this is the - multi-line body of example - #+END_SRC - -this code block: - - #+BEGIN_SRC sql :noweb yes - ---<<example>> - #+END_SRC - -expands to: - - #+BEGIN_SRC sql :noweb yes - ---this is the - ---multi-line body of example - #+END_SRC - - Since this change does not affect noweb replacement text without -newlines in them, inline noweb references are acceptable. - - This feature can also be used for management of indentation in -exported code snippets. With: - - #+NAME: if-true - #+BEGIN_SRC python :exports none - print('do things when true') - #+end_src - - #+name: if-false - #+begin_src python :exports none - print('do things when false') - #+end_src - -this code block: - - #+begin_src python :noweb yes :results output - if true: - <<if-true>> - else: - <<if-false>> - #+end_src - -expands to: - - if true: - print('do things when true') - else: - print('do things when false') - - When in doubt about the outcome of a source code block expansion, you -can preview the results with the following command: - -‘C-c C-v v’ or ‘C-c C-v C-v’ (‘org-babel-expand-src-block’) - Expand the current source code block according to its header - arguments and pop open the results in a preview buffer. - - ---------- Footnotes ---------- - - (1) For noweb literate programming details, see -<http://www.cs.tufts.edu/~nr/noweb/>. - - -File: org.info, Node: Library of Babel, Next: Key bindings and Useful Functions, Prev: Noweb Reference Syntax, Up: Working with Source Code - -16.12 Library of Babel -====================== - -The “Library of Babel” is a collection of code blocks. Like a function -library, these code blocks can be called from other Org files. A -collection of useful code blocks is available on Worg -(https://orgmode.org/worg/library-of-babel.html). For remote code block -evaluation syntax, see *note Evaluating Code Blocks::. - - For any user to add code to the library, first save the code in -regular code blocks of an Org file, and then load the Org file with -‘org-babel-lob-ingest’, which is bound to ‘C-c C-v i’. - - -File: org.info, Node: Key bindings and Useful Functions, Next: Batch Execution, Prev: Library of Babel, Up: Working with Source Code - -16.13 Key bindings and Useful Functions -======================================= - -Many common Org mode key sequences are re-bound depending on the -context. - - Active key bindings in code blocks: - -Key binding Function --------------------------------------------------------- -‘C-c C-c’ ‘org-babel-execute-src-block’ -‘C-c C-o’ ‘org-babel-open-src-block-result’ -‘M-<UP>’ ‘org-babel-load-in-session’ -‘M-<DOWN>’ ‘org-babel-pop-to-session’ - - Active key bindings in Org mode buffer: - -Key binding Function --------------------------------------------------------------------------- -‘C-c C-v p’ or ‘C-c C-v C-p’ ‘org-babel-previous-src-block’ -‘C-c C-v n’ or ‘C-c C-v C-n’ ‘org-babel-next-src-block’ -‘C-c C-v e’ or ‘C-c C-v C-e’ ‘org-babel-execute-maybe’ -‘C-c C-v o’ or ‘C-c C-v C-o’ ‘org-babel-open-src-block-result’ -‘C-c C-v v’ or ‘C-c C-v C-v’ ‘org-babel-expand-src-block’ -‘C-c C-v u’ or ‘C-c C-v C-u’ ‘org-babel-goto-src-block-head’ -‘C-c C-v g’ or ‘C-c C-v C-g’ ‘org-babel-goto-named-src-block’ -‘C-c C-v r’ or ‘C-c C-v C-r’ ‘org-babel-goto-named-result’ -‘C-c C-v b’ or ‘C-c C-v C-b’ ‘org-babel-execute-buffer’ -‘C-c C-v s’ or ‘C-c C-v C-s’ ‘org-babel-execute-subtree’ -‘C-c C-v d’ or ‘C-c C-v C-d’ ‘org-babel-demarcate-block’ -‘C-c C-v t’ or ‘C-c C-v C-t’ ‘org-babel-tangle’ -‘C-c C-v f’ or ‘C-c C-v C-f’ ‘org-babel-tangle-file’ -‘C-c C-v c’ or ‘C-c C-v C-c’ ‘org-babel-check-src-block’ -‘C-c C-v j’ or ‘C-c C-v C-j’ ‘org-babel-insert-header-arg’ -‘C-c C-v l’ or ‘C-c C-v C-l’ ‘org-babel-load-in-session’ -‘C-c C-v i’ or ‘C-c C-v C-i’ ‘org-babel-lob-ingest’ -‘C-c C-v I’ or ‘C-c C-v C-I’ ‘org-babel-view-src-block-info’ -‘C-c C-v z’ or ‘C-c C-v C-z’ ‘org-babel-switch-to-session-with-code’ -‘C-c C-v a’ or ‘C-c C-v C-a’ ‘org-babel-sha1-hash’ -‘C-c C-v h’ or ‘C-c C-v C-h’ ‘org-babel-describe-bindings’ -‘C-c C-v x’ or ‘C-c C-v C-x’ ‘org-babel-do-key-sequence-in-edit-buffer’ - - -File: org.info, Node: Batch Execution, Prev: Key bindings and Useful Functions, Up: Working with Source Code - -16.14 Batch Execution -===================== - -Org mode features, including working with source code facilities can be -invoked from the command line. This enables building shell scripts for -batch processing, running automated system tasks, and expanding Org -mode’s usefulness. - - The sample script shows batch processing of multiple files using -‘org-babel-tangle’. - - #!/bin/sh - # Tangle files with Org mode - # - emacs -Q --batch --eval " - (progn - (require 'ob-tangle) - (dolist (file command-line-args-left) - (with-current-buffer (find-file-noselect file) - (org-babel-tangle)))) - " "$@" - - -File: org.info, Node: Miscellaneous, Next: Hacking, Prev: Working with Source Code, Up: Top - -17 Miscellaneous -**************** - -* Menu: - -* Completion:: ‘M-<TAB>’ guesses completions. -* Structure Templates:: Quick insertion of structural elements. -* Speed Keys:: Electric commands at the beginning of a headline. -* Clean View:: Getting rid of leading stars in the outline. -* Execute commands in the active region:: Execute commands on multiple items in Org or agenda view. -* Dynamic Headline Numbering:: Display and update outline numbering. -* The Very Busy C-c C-c Key:: When in doubt, press ‘C-c C-c’. -* In-buffer Settings:: Overview of keywords. -* Regular Expressions:: Elisp regular expressions. -* Org Syntax:: Formal description of Org’s syntax. -* Documentation Access:: Read documentation about current syntax. -* Escape Character:: Prevent Org from interpreting your writing. -* Code Evaluation Security:: Org files evaluate in-line code. -* Interaction:: With other Emacs packages. -* TTY Keys:: Using Org on a tty. -* Protocols:: External access to Emacs and Org. -* Org Crypt:: Encrypting Org files. -* Org Mobile:: Viewing and capture on a mobile device. - - -File: org.info, Node: Completion, Next: Structure Templates, Up: Miscellaneous - -17.1 Completion -=============== - -Org has in-buffer completions. Unlike minibuffer completions, which are -useful for quick command interactions, Org’s in-buffer completions are -more suitable for content creation in Org documents. Type one or more -letters and invoke the hot key to complete the text in-place. Depending -on the context and the keys, Org offers different types of completions. -No minibuffer is involved. Such mode-specific hot keys have become an -integral part of Emacs and Org provides several shortcuts. - -‘M-<TAB>’ - - Complete word at point. - - • At the beginning of an empty headline, complete TODO keywords. - - • After ‘\’, complete TeX symbols supported by the exporter. - - • After ‘:’ in a headline, complete tags. Org deduces the list - of tags from the ‘TAGS’ in-buffer option (see *note Setting - Tags::), the variable ‘org-tag-alist’, or from all tags used - in the current buffer. - - • After ‘:’ and not in a headline, complete property keys. The - list of keys is constructed dynamically from all keys used in - the current buffer. - - • After ‘[[’, complete link abbreviations (see *note Link - Abbreviations::). - - • After ‘[[*’, complete headlines in the current buffer so that - they can be used in search links like: ‘[[*find this - headline]]’ - - • After ‘#+’, complete the special keywords like ‘TYP_TODO’ or - file-specific ‘OPTIONS’. After option keyword is complete, - pressing ‘M-<TAB>’ again inserts example settings for this - keyword. - - • After ‘STARTUP’ keyword, complete startup items. - - • When point is anywhere else, complete dictionary words using - Ispell. - - -File: org.info, Node: Structure Templates, Next: Speed Keys, Prev: Completion, Up: Miscellaneous - -17.2 Structure Templates -======================== - -With just a few keystrokes, it is possible to insert empty structural -blocks, such as ‘#+BEGIN_SRC’ ... ‘#+END_SRC’, or to wrap existing text -in such a block. - -‘C-c C-,’ (‘org-insert-structure-template’) - Prompt for a type of block structure, and insert the block at - point. If the region is active, it is wrapped in the block. First - prompts the user for keys, which are used to look up a structure - type from the variable below. If the key is ‘<TAB>’, ‘<RET>’, or - ‘<SPC>’, the user is prompted to enter a block type. - - Available structure types are defined in -‘org-structure-template-alist’, see the docstring for adding or changing -values. - - Org Tempo expands snippets to structures defined in -‘org-structure-template-alist’ and ‘org-tempo-keywords-alist’. For -example, ‘< s <TAB>’ creates a code block. Enable it by customizing -‘org-modules’ or add ‘(require 'org-tempo)’ to your Emacs init file(1). - -‘a’ ‘#+BEGIN_EXPORT ascii’ ... ‘#+END_EXPORT’ -‘c’ ‘#+BEGIN_CENTER’ ... ‘#+END_CENTER’ -‘C’ ‘#+BEGIN_COMMENT’ ... ‘#+END_COMMENT’ -‘e’ ‘#+BEGIN_EXAMPLE’ ... ‘#+END_EXAMPLE’ -‘E’ ‘#+BEGIN_EXPORT’ ... ‘#+END_EXPORT’ -‘h’ ‘#+BEGIN_EXPORT html’ ... ‘#+END_EXPORT’ -‘l’ ‘#+BEGIN_EXPORT latex’ ... ‘#+END_EXPORT’ -‘q’ ‘#+BEGIN_QUOTE’ ... ‘#+END_QUOTE’ -‘s’ ‘#+BEGIN_SRC’ ... ‘#+END_SRC’ -‘v’ ‘#+BEGIN_VERSE’ ... ‘#+END_VERSE’ - - ---------- Footnotes ---------- - - (1) For more information, please refer to the commentary section in -‘org-tempo.el’. - - -File: org.info, Node: Speed Keys, Next: Clean View, Prev: Structure Templates, Up: Miscellaneous - -17.3 Speed Keys -=============== - -Single keystrokes can execute custom commands in an Org file when point -is on a headline. Without the extra burden of a meta or modifier key, -Speed Keys can speed navigation or execute custom commands. Besides -faster navigation, Speed Keys may come in handy on small mobile devices -that do not have full keyboards. Speed Keys may also work on TTY -devices known for their problems when entering Emacs key chords. - - By default, Org has Speed Keys disabled. To activate Speed Keys, set -the variable ‘org-use-speed-commands’ to a non-‘nil’ value. To trigger -a Speed Key, point must be at the beginning of an Org headline, before -any of the stars. - - Org comes with a pre-defined list of Speed Keys. To add or modify -Speed Keys, customize the option ‘org-speed-commands’. For more -details, see the variable’s docstring. With Speed Keys activated, ‘M-x -org-speed-command-help’, or ‘?’ when point is at the beginning of an Org -headline, shows currently active Speed Keys, including the user-defined -ones. - - -File: org.info, Node: Clean View, Next: Execute commands in the active region, Prev: Speed Keys, Up: Miscellaneous - -17.4 A Cleaner Outline View -=========================== - -Org’s outline with stars and no indents can look cluttered for short -documents. For _book-like_ long documents, the effect is not as -noticeable. Org provides an alternate stars and indentation scheme, as -shown on the right in the following table. It displays only one star -and indents text to line up with the heading: - - * Top level headline | * Top level headline - ** Second level | * Second level - *** Third level | * Third level - some text | some text - *** Third level | * Third level - more text | more text - * Another top level headline | * Another top level headline - - Org can achieve this in two ways, (1) by just displaying the buffer -in this way without changing it, or (2) by actually indenting every line -in the desired amount with hard spaces and hiding leading stars. - -* Menu: - -* Org Indent Mode:: -* Hard indentation:: - - -File: org.info, Node: Org Indent Mode, Next: Hard indentation, Up: Clean View - -17.4.1 Org Indent Mode ----------------------- - -To display the buffer in the indented view, activate Org Indent minor -mode, using ‘M-x org-indent-mode’. Text lines that are not headlines -are prefixed with virtual spaces to vertically align with the headline -text(1). - - To make more horizontal space, the headlines are shifted by two -characters. Configure ‘org-indent-indentation-per-level’ variable for a -different number. - - By default, Org Indent mode turns off ‘org-adapt-indentation’ and -does hide leading stars by locally setting ‘org-hide-leading-stars’ to -‘t’: only one star on each headline is visible, the rest are masked with -the same font color as the background. If you want to customize this -default behavior, see ‘org-indent-mode-turns-on-hiding-stars’ and -‘org-indent-mode-turns-off-org-adapt-indentation’. - - To globally turn on Org Indent mode for all files, customize the -variable ‘org-startup-indented’. To control it for individual files, -use ‘STARTUP’ keyword as follows: - - #+STARTUP: indent - #+STARTUP: noindent - - ---------- Footnotes ---------- - - (1) Org Indent mode also sets ‘wrap-prefix’ correctly for indenting -and wrapping long lines of headlines or text. This minor mode also -handles Visual Line mode and directly applied settings through -‘word-wrap’. - - -File: org.info, Node: Hard indentation, Prev: Org Indent Mode, Up: Clean View - -17.4.2 Hard indentation ------------------------ - -It is possible to use hard spaces to achieve the indentation instead, if -the bare ASCII file should have the indented look also outside Emacs(1). -With Org’s support, you have to indent all lines to line up with the -outline headers. You would use these settings(2): - - (setq org-adapt-indentation t - org-hide-leading-stars t - org-odd-levels-only t) - -_Indentation of text below headlines_ (‘org-adapt-indentation’) - The first setting modifies paragraph filling, line wrapping, and - structure editing commands to preserving or adapting the - indentation as appropriate. - -_Hiding leading stars_ (‘org-hide-leading-stars’) - The second setting makes leading stars invisible by applying the - face ‘org-hide’ to them. For per-file preference, use these file - ‘STARTUP’ options: - - #+STARTUP: hidestars - #+STARTUP: showstars - -_Odd levels_ (‘org-odd-levels-only’) - The third setting makes Org use only odd levels, 1, 3, 5, ..., in - the outline to create more indentation. On a per-file level, - control this with: - - #+STARTUP: odd - #+STARTUP: oddeven - - To convert a file between single and double stars layouts, use ‘M-x - org-convert-to-odd-levels’ and ‘M-x org-convert-to-oddeven-levels’. - - ---------- Footnotes ---------- - - (1) This works, but requires extra effort. Org Indent mode is more -convenient for most applications. - - (2) ‘org-adapt-indentation’ can also be set to ‘'headline-data’, in -which case only data lines below the headline will be indented. - - -File: org.info, Node: Execute commands in the active region, Next: Dynamic Headline Numbering, Prev: Clean View, Up: Miscellaneous - -17.5 Execute commands in the active region -========================================== - -When in an Org buffer and the region is active, some commands will apply -to all the subtrees in the active region. For example, hitting ‘C-c -C-s’ when multiple headlines are within the active region will -successively prompt you for a new schedule date and time. To disable -this, set the option ‘org-loop-over-headlines-in-active-region’ to -non-‘t’, activate the region and run the command normally. - - ‘org-agenda-loop-over-headlines-in-active-region’ is the equivalent -option of the agenda buffer, where you can also use *note bulk editing -of selected entries: Bulk remote editing selected entries. - - Not all commands can loop in the active region and what subtrees or -headlines are considered can be refined: see the docstrings of these -options for more details. - - -File: org.info, Node: Dynamic Headline Numbering, Next: The Very Busy C-c C-c Key, Prev: Execute commands in the active region, Up: Miscellaneous - -17.6 Dynamic Headline Numbering -=============================== - -The Org Num minor mode, toggled with ‘M-x org-num-mode’, displays -outline numbering on top of headlines. It also updates it automatically -upon changes to the structure of the document. - - By default, all headlines are numbered. You can limit numbering to -specific headlines according to their level, tags, ‘COMMENT’ keyword, or -‘UNNUMBERED’ property. Set ‘org-num-max-level’, ‘org-num-skip-tags’, -‘org-num-skip-commented’, ‘org-num-skip-unnumbered’, or -‘org-num-skip-footnotes’ accordingly. - - If ‘org-num-skip-footnotes’ is non-‘nil’, footnotes sections (see -*note Creating Footnotes::) are not numbered either. - - You can control how the numbering is displayed by setting -‘org-num-face’ and ‘org-num-format-function’. - - You can also turn this mode globally for all Org files by setting the -option ‘org-startup-numerated’ to ‘t’, or locally on a file by using -‘#+startup: num’. - - -File: org.info, Node: The Very Busy C-c C-c Key, Next: In-buffer Settings, Prev: Dynamic Headline Numbering, Up: Miscellaneous - -17.7 The Very Busy ‘C-c C-c’ Key -================================ - -The ‘C-c C-c’ key in Org serves many purposes depending on the context. -It is probably the most over-worked, multi-purpose key combination in -Org. Its uses are well documented throughout this manual, but here is a -consolidated list for easy reference. - - • If column view (see *note Column View::) is on, exit column view. - - • If any highlights shown in the buffer from the creation of a sparse - tree, or from clock display, remove such highlights. - - • If point is in one of the special ‘KEYWORD’ lines, scan the buffer - for these lines and update the information. Also reset the Org - file cache used to temporary store the contents of URLs used as - values for keywords like ‘SETUPFILE’. - - • If point is inside a table, realign the table. - - • If point is on a ‘TBLFM’ keyword, re-apply the formulas to the - entire table. - - • If the current buffer is a capture buffer, close the note and file - it. With a prefix argument, also jump to the target location after - saving the note. - - • If point is on a ‘<<<target>>>’, update radio targets and - corresponding links in this buffer. - - • If point is on a property line or at the start or end of a property - drawer, offer property commands. - - • If point is at a footnote reference, go to the corresponding - definition, and _vice versa_. - - • If point is on a statistics cookie, update it. - - • If point is in a plain list item with a checkbox, toggle the status - of the checkbox. - - • If point is on a numbered item in a plain list, renumber the - ordered list. - - • If point is on the ‘#+BEGIN’ line of a dynamic block, the block is - updated. - - • If point is at a timestamp, fix the day name in the timestamp. - - -File: org.info, Node: In-buffer Settings, Next: Regular Expressions, Prev: The Very Busy C-c C-c Key, Up: Miscellaneous - -17.8 Summary of In-Buffer Settings -================================== - -In-buffer settings start with ‘#+’, followed by a keyword, a colon, and -then a word for each setting. Org accepts multiple settings on the same -line. Org also accepts multiple lines for a keyword. This manual -describes these settings throughout. A summary follows here. - - ‘C-c C-c’ activates any changes to the in-buffer settings. Closing -and reopening the Org file in Emacs also activates the changes. - -‘#+ARCHIVE: %s_done::’ - Sets the archive location of the agenda file. The corresponding - variable is ‘org-archive-location’. - -‘#+CATEGORY’ - Sets the category of the agenda file, which applies to the entire - document. - -‘#+COLUMNS: %25ITEM ...’ - Set the default format for columns view. This format applies when - columns view is invoked in locations where no ‘COLUMNS’ property - applies. - -‘#+CONSTANTS: name1=value1 ...’ - Set file-local values for constants that table formulas can use. - This line sets the local variable - ‘org-table-formula-constants-local’. The global version of this - variable is ‘org-table-formula-constants’. - -‘#+FILETAGS: :tag1:tag2:tag3:’ - Set tags that all entries in the file inherit from, including the - top-level entries. - -‘#+LINK: linkword replace’ - Each line specifies one abbreviation for one link. Use multiple - ‘LINK’ keywords for more, see *note Link Abbreviations::. The - corresponding variable is ‘org-link-abbrev-alist’. - -‘#+PRIORITIES: highest lowest default’ - This line sets the limits and the default for the priorities. All - three must be either letters A–Z or numbers 0–9. The highest - priority must have a lower ASCII number than the lowest priority. - -‘#+PROPERTY: Property_Name Value’ - This line sets a default inheritance value for entries in the - current buffer, most useful for specifying the allowed values of a - property. - -‘#+SETUPFILE: file’ - The setup file or a URL pointing to such file is for additional - in-buffer settings. Org loads this file and parses it for any - settings in it only when Org opens the main file. If URL is - specified, the contents are downloaded and stored in a temporary - file cache. ‘C-c C-c’ on the settings line parses and loads the - file, and also resets the temporary file cache. Org also parses - and loads the document during normal exporting process. Org parses - the contents of this document as if it was included in the buffer. - It can be another Org file. To visit the file—not a URL—use ‘C-c - '’ while point is on the line with the file name. - -‘#+STARTUP:’ - Startup options Org uses when first visiting a file. - - The first set of options deals with the initial visibility of the - outline tree. The corresponding variable for global default - settings is ‘org-startup-folded’ with a default value of - ‘showeverything’. - - ‘overview’ Top-level headlines only. - ‘content’ All headlines. - ‘showall’ No folding on any entry. - ‘show2levels’ Headline levels 1-2. - ‘show3levels’ Headline levels 1-3. - ‘show4levels’ Headline levels 1-4. - ‘show5levels’ Headline levels 1-5. - ‘showeverything’ Show even drawer contents. - - Dynamic virtual indentation is controlled by the variable - ‘org-startup-indented’(1). - - ‘indent’ Start with Org Indent mode turned on. - ‘noindent’ Start with Org Indent mode turned off. - - Dynamic virtual numeration of headlines is controlled by the - variable ‘org-startup-numerated’. - - ‘num’ Start with Org num mode turned on. - ‘nonum’ Start with Org num mode turned off. - - Aligns tables consistently upon visiting a file. The corresponding - variable is ‘org-startup-align-all-tables’ with ‘nil’ as default - value. - - ‘align’ Align all tables. - ‘noalign’ Do not align tables on startup. - - Shrink table columns with a width cookie. The corresponding - variable is ‘org-startup-shrink-all-tables’ with ‘nil’ as default - value. - - When visiting a file, inline images can be automatically displayed. - The corresponding variable is ‘org-startup-with-inline-images’, - with a default value ‘nil’ to avoid delays when visiting a file. - - ‘inlineimages’ Show inline images. - ‘noinlineimages’ Do not show inline images on startup. - - Logging the closing and reopening of TODO items and clock intervals - can be configured using these options (see variables - ‘org-log-done’, ‘org-log-note-clock-out’, and ‘org-log-repeat’). - - ‘logdone’ Record a timestamp when an item is marked as done. - ‘lognotedone’ Record timestamp and a note when DONE. - ‘nologdone’ Do not record when items are marked as done. - ‘logrepeat’ Record a time when reinstating a repeating item. - ‘lognoterepeat’ Record a note when reinstating a repeating item. - ‘nologrepeat’ Do not record when reinstating repeating item. - ‘lognoteclock-out’ Record a note when clocking out. - ‘nolognoteclock-out’ Do not record a note when clocking out. - ‘logreschedule’ Record a timestamp when scheduling time changes. - ‘lognotereschedule’ Record a note when scheduling time changes. - ‘nologreschedule’ Do not record when a scheduling date changes. - ‘logredeadline’ Record a timestamp when deadline changes. - ‘lognoteredeadline’ Record a note when deadline changes. - ‘nologredeadline’ Do not record when a deadline date changes. - ‘logrefile’ Record a timestamp when refiling. - ‘lognoterefile’ Record a note when refiling. - ‘nologrefile’ Do not record when refiling. - - Here are the options for hiding leading stars in outline headings, - and for indenting outlines. The corresponding variables are - ‘org-hide-leading-stars’ and ‘org-odd-levels-only’, both with a - default setting ‘nil’ (meaning ‘showstars’ and ‘oddeven’). - - ‘hidestars’ Make all but one of the stars starting a headline invisible. - ‘showstars’ Show all stars starting a headline. - ‘indent’ Virtual indentation according to outline level. - ‘noindent’ No virtual indentation according to outline level. - ‘odd’ Allow only odd outline levels (1, 3, ...). - ‘oddeven’ Allow all outline levels. - - To turn on custom format overlays over timestamps (variables - ‘org-put-time-stamp-overlays’ and - ‘org-time-stamp-overlay-formats’), use: - - ‘customtime’ Overlay custom time format. - - The following options influence the table spreadsheet (variable - ‘constants-unit-system’). - - ‘constcgs’ ‘constants.el’ should use the c-g-s unit system. - ‘constSI’ ‘constants.el’ should use the SI unit system. - - To influence footnote settings, use the following keywords. The - corresponding variables are ‘org-footnote-define-inline’, - ‘org-footnote-auto-label’, and ‘org-footnote-auto-adjust’. - - ‘fninline’ Define footnotes inline. - ‘fnnoinline’ Define footnotes in separate section. - ‘fnlocal’ Define footnotes near first reference, but not inline. - ‘fnprompt’ Prompt for footnote labels. - ‘fnauto’ Create ‘[fn:1]’-like labels automatically (default). - ‘fnconfirm’ Offer automatic label for editing or confirmation. - ‘fnadjust’ Automatically renumber and sort footnotes. - ‘nofnadjust’ Do not renumber and sort automatically. - - To hide blocks on startup, use these keywords. The corresponding - variable is ‘org-hide-block-startup’. - - ‘hideblocks’ Hide all begin/end blocks on startup. - ‘nohideblocks’ Do not hide blocks on startup. - - The display of entities as UTF-8 characters is governed by the - variable ‘org-pretty-entities’ and the keywords - - ‘entitiespretty’ Show entities as UTF-8 characters where possible. - ‘entitiesplain’ Leave entities plain. - -‘#+TAGS: TAG1(c1) TAG2(c2)’ - These lines (several such lines are allowed) specify the valid tags - in this file, and (potentially) the corresponding _fast tag - selection_ keys. The corresponding variable is ‘org-tag-alist’. - -‘#+TODO:’ -‘#+SEQ_TODO:’ -‘#+TYP_TODO:’ - These lines set the TODO keywords and their interpretation in the - current file. The corresponding variable is ‘org-todo-keywords’. - - ---------- Footnotes ---------- - - (1) Note that Org Indent mode also sets the ‘wrap-prefix’ property, -such that Visual Line mode (or purely setting ‘word-wrap’) wraps long -lines, including headlines, correctly indented. - - -File: org.info, Node: Regular Expressions, Next: Org Syntax, Prev: In-buffer Settings, Up: Miscellaneous - -17.9 Regular Expressions -======================== - -Org, as an Emacs mode, makes use of Elisp regular expressions for -searching, matching and filtering. Elisp regular expressions have a -somewhat different syntax then some common standards. Most notably, -alternation is indicated using ‘\|’ and matching groups are denoted by -‘\(...\)’. For example the string ‘home\|work’ matches either ‘home’ or -‘work’. - - For more information, see *note Regular Expressions in Emacs: -(emacs)Regexps. - - -File: org.info, Node: Org Syntax, Next: Documentation Access, Prev: Regular Expressions, Up: Miscellaneous - -17.10 Org Syntax -================ - -A reference document providing a formal description of Org’s syntax is -available as a draft on Worg -(https://orgmode.org/worg/dev/org-syntax.html), written and maintained -by Nicolas Goaziou. It defines Org’s core internal concepts such as -“headlines”, “sections”, “affiliated keywords”, “(greater) elements” and -“objects”. Each part of an Org document belongs to one of the previous -categories. - - To explore the abstract structure of an Org buffer, run this in a -buffer: - - M-: (org-element-parse-buffer) <RET> - -It outputs a list containing the buffer’s content represented as an -abstract structure. The export engine relies on the information stored -in this list. Most interactive commands—e.g., for structure -editing—also rely on the syntactic meaning of the surrounding context. - - You can probe the syntax of your documents with the command - - M-x org-lint <RET> - -It runs a number of checks to find common mistakes. It then displays -their location in a dedicated buffer, along with a description and a -“trust level”, since false-positive are possible. From there, you can -operate on the reports with the following keys: - -‘C-j’, ‘<TAB>’ Display the offending line -‘<RET>’ Move point to the offending line -‘g’ Check the document again -‘h’ Hide all reports from the same checker -‘i’ Also remove them from all subsequent checks -‘S’ Sort reports by the column at point - - -File: org.info, Node: Documentation Access, Next: Escape Character, Prev: Org Syntax, Up: Miscellaneous - -17.11 Context Dependent Documentation -===================================== - -‘C-c C-x I’ in an Org file tries to open a suitable section of the Org -manual depending on the syntax at point. For example, using it on a -headline displays “Document Structure” section. - - ‘q’ closes the Info window. - - -File: org.info, Node: Escape Character, Next: Code Evaluation Security, Prev: Documentation Access, Up: Miscellaneous - -17.12 Escape Character -====================== - -You may sometimes want to write text that looks like Org syntax, but -should really read as plain text. Org may use a specific escape -character in some situations, i.e., a backslash in macros (see *note -Macro Replacement::) and links (see *note Link Format::), or a comma in -source and example blocks (see *note Literal Examples::). In the -general case, however, we suggest to use the zero width space. You can -insert one with any of the following: - - C-x 8 <RET> zero width space <RET> - C-x 8 <RET> 200B <RET> - - For example, in order to write ‘[[1,2]]’ as-is in your document, you -may write instead - - [X[1,2]] - - where ‘X’ denotes the zero width space character. - - -File: org.info, Node: Code Evaluation Security, Next: Interaction, Prev: Escape Character, Up: Miscellaneous - -17.13 Code Evaluation and Security Issues -========================================= - -Unlike plain text, running code comes with risk. Each source code -block, in terms of risk, is equivalent to an executable file. Org -therefore puts a few confirmation prompts by default. This is to alert -the casual user from accidentally running untrusted code. - - For users who do not run code blocks or write code regularly, Org’s -default settings should suffice. However, some users may want to tweak -the prompts for fewer interruptions. To weigh the risks of automatic -execution of code blocks, here are some details about code evaluation. - - Org evaluates code in the following circumstances: - -_Source code blocks_ - Org evaluates source code blocks in an Org file during export. Org - also evaluates a source code block with the ‘C-c C-c’ key chord. - Users exporting or running code blocks must load files only from - trusted sources. Be wary of customizing variables that remove or - alter default security measures. - - -- User Option: org-confirm-babel-evaluate - When ‘t’, Org prompts the user for confirmation before - executing each code block. When ‘nil’, Org executes code - blocks without prompting the user for confirmation. When this - option is set to a custom function, Org invokes the function - with these two arguments: the source code language and the - body of the code block. The custom function must return - either a ‘t’ or ‘nil’, which determines if the user is - prompted. Each source code language can be handled separately - through this function argument. - - For example, here is how to execute ditaa code blocks without - prompting: - - (defun my-org-confirm-babel-evaluate (lang body) - (not (string= lang "ditaa"))) ;don't ask for ditaa - (setq org-confirm-babel-evaluate #'my-org-confirm-babel-evaluate) - -_Following ‘shell’ and ‘elisp’ links_ - Org has two link types that can directly evaluate code (see *note - External Links::). Because such code is not visible, these links - have a potential risk. Org therefore prompts the user when it - encounters such links. The customization variables are: - - -- User Option: org-link-shell-confirm-function - Function that prompts the user before executing a shell link. - - -- User Option: org-link-elisp-confirm-function - Function that prompts the user before executing an Emacs Lisp - link. - -_Formulas in tables_ - Formulas in tables (see *note The Spreadsheet::) are code that is - evaluated either by the Calc interpreter, or by the Emacs Lisp - interpreter. - - -File: org.info, Node: Interaction, Next: TTY Keys, Prev: Code Evaluation Security, Up: Miscellaneous - -17.14 Interaction with Other Packages -===================================== - -Org’s compatibility and the level of interaction with other Emacs -packages are documented here. - -* Menu: - -* Cooperation:: Packages Org cooperates with. -* Conflicts:: Packages that lead to conflicts. - - -File: org.info, Node: Cooperation, Next: Conflicts, Up: Interaction - -17.14.1 Packages that Org cooperates with ------------------------------------------ - -‘calc.el’ by Dave Gillespie - - Org uses the Calc package for implementing spreadsheet - functionality in its tables (see *note The Spreadsheet::). Org - also uses Calc for embedded calculations. See *note GNU Emacs Calc - Manual: (calc)Embedded Mode. - -‘constants.el’ by Carsten Dominik - - Org can use names for constants in formulas in tables. Org can - also use calculation suffixes for units, such as ‘M’ for ‘Mega’. - For a standard collection of such constants, install the - ‘constants’ package. Install version 2.0 of this package, - available at <http://www.astro.uva.nl/~dominik/Tools>. Org checks - if the function ‘constants-get’ has been autoloaded. Installation - instructions are in the file ‘constants.el’. - -‘cdlatex.el’ by Carsten Dominik - - Org mode can make use of the CDLaTeX package to efficiently enter - LaTeX fragments into Org files. See *note CDLaTeX mode::. - -‘imenu.el’ by Ake Stenhoff and Lars Lindberg - - Imenu creates dynamic menus based on an index of items in a file. - Org mode supports Imenu menus. Enable it with a mode hook as - follows: - - (add-hook 'org-mode-hook - (lambda () (imenu-add-to-menubar "Imenu"))) - - By default the index is two levels deep—you can modify the depth - using the option ‘org-imenu-depth’. - -‘speedbar.el’ by Eric M. Ludlam - - Speedbar package creates a special Emacs frame for displaying files - and index items in files. Org mode supports Speedbar; users can - drill into Org files directly from the Speedbar. The ‘<’ in the - Speedbar frame tweaks the agenda commands to that file or to a - subtree. - -‘table.el’ by Takaaki Ota - - Complex ASCII tables with automatic line wrapping, column- and - row-spanning, and alignment can be created using the Emacs table - package by Takaaki Ota. Org mode recognizes such tables and - exports them properly. ‘C-c '’ to edit these tables in a special - buffer, much like Org’s code blocks. Because of interference with - other Org mode functionality, Takaaki Ota tables cannot be edited - directly in the Org buffer. - - ‘C-c '’ (‘org-edit-special’) - Edit a ‘table.el’ table. Works when point is in a ‘table.el’ - table. - - ‘C-c ~’ (‘org-table-create-with-table.el’) - Insert a ‘table.el’ table. If there is already a table at - point, this command converts it between the ‘table.el’ format - and the Org mode format. See the documentation string of the - command ‘org-convert-table’ for the restrictions under which - this is possible. - - -File: org.info, Node: Conflicts, Prev: Cooperation, Up: Interaction - -17.14.2 Packages that conflict with Org mode --------------------------------------------- - -In Emacs, shift-selection combines motions of point with shift key to -enlarge regions. Emacs sets this mode by default. This conflicts with -Org’s use of ‘S-<cursor>’ commands to change timestamps, TODO keywords, -priorities, and item bullet types, etc. Since ‘S-<cursor>’ commands -outside of specific contexts do not do anything, Org offers the variable -‘org-support-shift-select’ for customization. Org mode accommodates -shift selection by (i) making it available outside of the special -contexts where special commands apply, and (ii) extending an existing -active region even if point moves across a special context. - -‘cua.el’ by Kim F. Storm - Org key bindings conflict with ‘S-<cursor>’ keys used by CUA mode. - For Org to relinquish these bindings to CUA mode, configure the - variable ‘org-replace-disputed-keys’. When set, Org moves the - following key bindings in Org files, and in the agenda buffer—but - not during date selection. - - ‘S-<UP>’ ⇒ ‘M-p’ ‘S-<DOWN>’ ⇒ ‘M-n’ - ‘S-<LEFT>’ ⇒ ‘M--’ ‘S-<RIGHT>’ ⇒ ‘M-+’ - ‘C-S-<LEFT>’ ⇒ ‘M-S--’ ‘C-S-<RIGHT>’ ⇒ ‘M-S-+’ - - Yes, these are unfortunately more difficult to remember. If you - want to have other replacement keys, look at the variable - ‘org-disputed-keys’. - -‘ecomplete.el’ by Lars Magne Ingebrigtsen - Ecomplete provides “electric” address completion in address header - lines in message buffers. Sadly Orgtbl mode cuts Ecomplete’s power - supply: no completion happens when Orgtbl mode is enabled in - message buffers while entering text in address header lines. If - one wants to use ecomplete one should _not_ follow the advice to - automagically turn on Orgtbl mode in message buffers (see *note - Orgtbl Mode::), but instead—after filling in the message - headers—turn on Orgtbl mode manually when needed in the messages - body. - -‘filladapt.el’ by Kyle Jones - Org mode tries to do the right thing when filling paragraphs, list - items and other elements. Many users reported problems using both - ‘filladapt.el’ and Org mode, so a safe thing to do is to disable - filladapt like this: - - (add-hook 'org-mode-hook 'turn-off-filladapt-mode) - -‘viper.el’ by Michael Kifer - - Viper uses ‘C-c /’ and therefore makes this key not access the - corresponding Org mode command ‘org-sparse-tree’. You need to find - another key for this command, or override the key in - ‘viper-vi-global-user-map’ with - - (define-key viper-vi-global-user-map "C-c /" 'org-sparse-tree) - -‘windmove.el’ by Hovav Shacham - - This package also uses the ‘S-<cursor>’ keys, so everything written - in the paragraph above about CUA mode also applies here. If you - want to make the windmove function active in locations where Org - mode does not have special functionality on ‘S-<cursor>’, add this - to your configuration: - - ;; Make windmove work in Org mode: - (add-hook 'org-shiftup-final-hook 'windmove-up) - (add-hook 'org-shiftleft-final-hook 'windmove-left) - (add-hook 'org-shiftdown-final-hook 'windmove-down) - (add-hook 'org-shiftright-final-hook 'windmove-right) - -‘yasnippet.el’ - The way Org mode binds the ‘<TAB>’ key (binding to ‘[tab]’ instead - of ‘"\t"’) overrules YASnippet’s access to this key. The following - code fixed this problem: - - (add-hook 'org-mode-hook - (lambda () - (setq-local yas/trigger-key [tab]) - (define-key yas/keymap [tab] 'yas/next-field-or-maybe-expand))) - - The latest version of YASnippet does not play well with Org mode. - If the above code does not fix the conflict, start by defining the - following function: - - (defun yas/org-very-safe-expand () - (let ((yas/fallback-behavior 'return-nil)) (yas/expand))) - - Then, tell Org mode to use that function: - - (add-hook 'org-mode-hook - (lambda () - (make-variable-buffer-local 'yas/trigger-key) - (setq yas/trigger-key [tab]) - (add-to-list 'org-tab-first-hook 'yas/org-very-safe-expand) - (define-key yas/keymap [tab] 'yas/next-field))) - - -File: org.info, Node: TTY Keys, Next: Protocols, Prev: Interaction, Up: Miscellaneous - -17.15 Using Org on a TTY -======================== - -Org provides alternative key bindings for TTY and modern mobile devices -that cannot perform movement commands on point and key bindings with -modifier keys. Some of these workarounds may be more cumbersome than -necessary. Users should look into customizing these further based on -their usage needs. For example, the normal ‘S-<cursor>’ for editing -timestamp might be better with ‘C-c .’ chord. - -Default Alternative 1 Speed key Alternative 2 ----------------------------------------------------------------- -‘S-<TAB>’ ‘C-u <TAB>’ ‘C’ -‘M-<LEFT>’ ‘C-c C-x l’ ‘l’ ‘Esc <LEFT>’ -‘M-S-<LEFT>’ ‘C-c C-x L’ ‘L’ -‘M-<RIGHT>’ ‘C-c C-x r’ ‘r’ ‘Esc <RIGHT>’ -‘M-S-<RIGHT>’ ‘C-c C-x R’ ‘R’ -‘M-<UP>’ ‘C-c C-x u’ ‘Esc <UP>’ -‘M-S-<UP>’ ‘C-c C-x U’ ‘U’ -‘M-<DOWN>’ ‘C-c C-x d’ ‘Esc <DOWN>’ -‘M-S-<DOWN>’ ‘C-c C-x D’ ‘D’ -‘S-<RET>’ ‘C-c C-x c’ -‘M-<RET>’ ‘C-c C-x m’ ‘Esc <RET>’ -‘M-S-<RET>’ ‘C-c C-x M’ -‘S-<LEFT>’ ‘C-c <LEFT>’ -‘S-<RIGHT>’ ‘C-c <RIGHT>’ -‘S-<UP>’ ‘C-c <UP>’ -‘S-<DOWN>’ ‘C-c <DOWN>’ -‘C-S-<LEFT>’ ‘C-c C-x <LEFT>’ -‘C-S-<RIGHT>’ ‘C-c C-x <RIGHT>’ - - -File: org.info, Node: Protocols, Next: Org Crypt, Prev: TTY Keys, Up: Miscellaneous - -17.16 Protocols for External Access -=================================== - -Org protocol is a tool to trigger custom actions in Emacs from external -applications. Any application that supports calling external programs -with an URL as argument may be used with this functionality. For -example, you can configure bookmarks in your web browser to send a link -to the current page to Org and create a note from it using capture (see -*note Capture::). You can also create a bookmark that tells Emacs to -open the local source file of a remote website you are browsing. - - In order to use Org protocol from an application, you need to -register ‘org-protocol://’ as a valid scheme-handler. External calls -are passed to Emacs through the ‘emacsclient’ command, so you also need -to ensure an Emacs server is running. More precisely, when the -application calls - - emacsclient "org-protocol://PROTOCOL?key1=val1&key2=val2" - -Emacs calls the handler associated to PROTOCOL with argument ‘(:key1 -val1 :key2 val2)’. - - Org protocol comes with three predefined protocols, detailed in the -following sections. Configure ‘org-protocol-protocol-alist’ to define -your own. - -* Menu: - -* The store-link protocol:: Store a link, push URL to kill-ring. -* The capture protocol:: Fill a buffer with external information. -* The open-source protocol:: Edit published contents. - - -File: org.info, Node: The store-link protocol, Next: The capture protocol, Up: Protocols - -17.16.1 The ‘store-link’ protocol ---------------------------------- - -Using the ‘store-link’ handler, you can copy links, to that they can be -inserted using ‘M-x org-insert-link’ or yanking. More precisely, the -command - - emacsclient "org-protocol://store-link?url=URL&title=TITLE" - -stores the following link: - - [[URL][TITLE]] - - In addition, URL is pushed on the kill-ring for yanking. You need to -encode URL and TITLE if they contain slashes, and probably quote those -for the shell. - - To use this feature from a browser, add a bookmark with an arbitrary -name, e.g., ‘Org: store-link’ and enter this as _Location_: - - javascript:location.href='org-protocol://store-link?' + - new URLSearchParams({url:location.href, title:document.title}); - - Title is an optional parameter. Another expression was recommended -earlier: - - javascript:location.href='org-protocol://store-link?url='+ - encodeURIComponent(location.href); - - The latter form is compatible with older Org versions from 9.0 to -9.4. - - -File: org.info, Node: The capture protocol, Next: The open-source protocol, Prev: The store-link protocol, Up: Protocols - -17.16.2 The ‘capture’ protocol ------------------------------- - -Activating the “capture” handler pops up a ‘Capture’ buffer in Emacs, -using acapture template. - - emacsclient "org-protocol://capture?template=X&url=URL&title=TITLE&body=BODY" - - To use this feature, add a bookmark with an arbitrary name, e.g., -‘Org: capture’, and enter this as ‘Location’: - - javascript:location.href='org-protocol://capture?' + - new URLSearchParams({ - template: 'x', url: window.location.href, - title: document.title, body: window.getSelection()}); - - You might have seen another expression: - - javascript:location.href='org-protocol://capture?template=x'+ - '&url='+encodeURIComponent(window.location.href)+ - '&title='+encodeURIComponent(document.title)+ - '&body='+encodeURIComponent(window.getSelection()); - - It is a bit more cluttered than the former one, but it is compatible -with previous Org versions 9.0-9.4. In these versions encoding of space -as “+” character was not supported by URI decoder. - - The capture template to be used can be specified in the bookmark -(like ‘X’ above). If unspecified, the template key is set in the -variable ‘org-protocol-default-template-key’. The following template -placeholders are available: - - %:link The URL - %:description The webpage title - %:annotation Equivalent to [[%:link][%:description]] - %i The selected text - - -File: org.info, Node: The open-source protocol, Prev: The capture protocol, Up: Protocols - -17.16.3 The ‘open-source’ protocol ----------------------------------- - -The ‘open-source’ handler is designed to help with editing local sources -when reading a document. To that effect, you can use a bookmark with -the following location: - - javascript:location.href='org-protocol://open-source?&url='+ - encodeURIComponent(location.href) - - The variable ‘org-protocol-project-alist’ maps URLs to local file -names, by stripping URL parameters from the end and replacing the -‘:base-url’ with ‘:working-directory’ and ‘:online-suffix’ with -‘:working-suffix’. For example, assuming you own a local copy of -‘https://orgmode.org/worg/’ contents at ‘/home/user/worg’, you can set -‘org-protocol-project-alist’ to the following - - (setq org-protocol-project-alist - '(("Worg" - :base-url "https://orgmode.org/worg/" - :working-directory "/home/user/worg/" - :online-suffix ".html" - :working-suffix ".org"))) - -If you are now browsing -‘https://orgmode.org/worg/org-contrib/org-protocol.html’ and find a typo -or have an idea about how to enhance the documentation, simply click the -bookmark and start editing. - - However, such mapping may not always yield the desired results. -Suppose you maintain an online store located at ‘https://example.com/’. -The local sources reside in ‘/home/user/example/’. It is common -practice to serve all products in such a store through one file and -rewrite URLs that do not match an existing file on the server. That -way, a request to ‘https://example.com/print/posters.html’ might be -rewritten on the server to something like -‘https://example.com/shop/products.php/posters.html.php’. The -‘open-source’ handler probably cannot find a file named -‘/home/user/example/print/posters.html.php’ and fails. - - Such an entry in ‘org-protocol-project-alist’ may hold an additional -property ‘:rewrites’. This property is a list of cons cells, each of -which maps a regular expression to a path relative to the -‘:working-directory’. - - Now map the URL to the path ‘/home/user/example/products.php’ by -adding ‘:rewrites’ rules like this: - - (setq org-protocol-project-alist - '(("example.com" - :base-url "https://example.com/" - :working-directory "/home/user/example/" - :online-suffix ".php" - :working-suffix ".php" - :rewrites (("example.com/print/" . "products.php") - ("example.com/$" . "index.php"))))) - -Since ‘example.com/$’ is used as a regular expression, it maps -‘http://example.com/’, ‘https://example.com’, ‘http://www.example.com/’ -and similar to ‘/home/user/example/index.php’. - - The ‘:rewrites’ rules are searched as a last resort if and only if no -existing file name is matched. - - Two functions can help you filling ‘org-protocol-project-alist’ with -valid contents: ‘org-protocol-create’ and ‘org-protocol-create-for-org’. -The latter is of use if you’re editing an Org file that is part of a -publishing project. - - -File: org.info, Node: Org Crypt, Next: Org Mobile, Prev: Protocols, Up: Miscellaneous - -17.17 Org Crypt -=============== - -Org Crypt encrypts the text of an entry, but not the headline, or -properties. Behind the scene, it uses the *note Emacs EasyPG Library: -(epa)Top. to encrypt and decrypt files, and EasyPG needs a correct *note -GnuPG: (gnupg)Top. setup. - - Any text below a headline that has a ‘crypt’ tag is automatically -encrypted when the file is saved. To use a different tag, customize the -‘org-crypt-tag-matcher’ setting. - - Here is a suggestion for Org Crypt settings in Emacs init file: - - (require 'org-crypt) - (org-crypt-use-before-save-magic) - (setq org-tags-exclude-from-inheritance '("crypt")) - - (setq org-crypt-key nil) - ;; GPG key to use for encryption - ;; Either the Key ID or set to nil to use symmetric encryption. - - (setq auto-save-default nil) - ;; Auto-saving does not cooperate with org-crypt.el: so you need to - ;; turn it off if you plan to use org-crypt.el quite often. Otherwise, - ;; you'll get an (annoying) message each time you start Org. - - ;; To turn it off only locally, you can insert this: - ;; - ;; # -*- buffer-auto-save-file-name: nil; -*- - - It’s possible to use different keys for different headings by -specifying the respective key as property ‘CRYPTKEY’, e.g.: - - * Totally secret :crypt: - :PROPERTIES: - :CRYPTKEY: 0x0123456789012345678901234567890123456789 - :END: - - Excluding the ‘crypt’ tag from inheritance prevents already encrypted -text from being encrypted again. - - -File: org.info, Node: Org Mobile, Prev: Org Crypt, Up: Miscellaneous - -17.18 Org Mobile -================ - -Org Mobile is a protocol for synchronizing Org files between Emacs and -other applications, e.g., on mobile devices. It enables offline-views -and capture support for an Org mode system that is rooted on a “real” -computer. The external application can also record changes to existing -entries. - - This appendix describes Org’s support for agenda view formats -compatible with Org Mobile. It also describes synchronizing changes, -such as to notes, between the mobile application and the computer. - - To change tags and TODO states in the mobile application, first -customize the variables ‘org-todo-keywords’, ‘org-tag-alist’ and -‘org-tag-persistent-alist’. These should cover all the important tags -and TODO keywords, even if Org files use only some of them. Though the -mobile application is expected to support in-buffer settings, it is -required to understand TODO states _sets_ (see *note Per-file -keywords::) and _mutually exclusive_ tags (see *note Setting Tags::) -only for those set in these variables. - -* Menu: - -* Setting up the staging area:: For the mobile device. -* Pushing to the mobile application:: Uploading Org files and agendas. -* Pulling from the mobile application:: Integrating captured and flagged items. - - -File: org.info, Node: Setting up the staging area, Next: Pushing to the mobile application, Up: Org Mobile - -17.18.1 Setting up the staging area ------------------------------------ - -The mobile application needs access to a file directory on a server(1) -to interact with Emacs. Pass its location through the -‘org-mobile-directory’ variable. If you can mount that directory -locally just set the variable to point to that directory: - - (setq org-mobile-directory "~/orgmobile/") - - Alternatively, by using TRAMP (see *note TRAMP User Manual: -(tramp)Top.), ‘org-mobile-directory’ may point to a remote directory -accessible through, for example, SSH, SCP, or DAVS: - - (setq org-mobile-directory "/davs:user@remote.host:/org/webdav/") - - With a public server, consider encrypting the files. Org also -requires OpenSSL installed on the local computer. To turn on -encryption, set the same password in the mobile application and in -Emacs. Set the password in the variable ‘org-mobile-use-encryption’(2). -Note that even after the mobile application encrypts the file contents, -the file name remains visible on the file systems of the local computer, -the server, and the mobile device. - - ---------- Footnotes ---------- - - (1) For a server to host files, consider using a WebDAV server, such -as Nextcloud (https://nextcloud.com). Additional help is at this FAQ -entry (https://orgmode.org/worg/org-faq.html#mobileorg_webdav). - - (2) If Emacs is configured for safe storing of passwords, then -configure the variable ‘org-mobile-encryption-password’; please read the -docstring of that variable. - - -File: org.info, Node: Pushing to the mobile application, Next: Pulling from the mobile application, Prev: Setting up the staging area, Up: Org Mobile - -17.18.2 Pushing to the mobile application ------------------------------------------ - -The command ‘org-mobile-push’ copies files listed in ‘org-mobile-files’ -into the staging area. Files include agenda files (as listed in -‘org-agenda-files’). Customize ‘org-mobile-files’ to add other files. -File names are staged with paths relative to ‘org-directory’, so all -files should be inside this directory(1). - - Push creates a special Org file ‘agendas.org’ with custom agenda -views defined by the user(2). - - Finally, Org writes the file ‘index.org’, containing links to other -files. The mobile application reads this file first from the server to -determine what other files to download for agendas. For faster -downloads, it is expected to only read files whose checksums(3) have -changed. - - ---------- Footnotes ---------- - - (1) Symbolic links in ‘org-directory’ need to have the same name as -their targets. - - (2) While creating the agendas, Org mode forces ‘ID’ properties on -all referenced entries, so that these entries can be uniquely identified -if Org Mobile flags them for further action. To avoid setting -properties configure the variable ‘org-mobile-force-id-on-agenda-items’ -to ‘nil’. Org mode then relies on outline paths, assuming they are -unique. - - (3) Checksums are stored automatically in the file ‘checksums.dat’. - - -File: org.info, Node: Pulling from the mobile application, Prev: Pushing to the mobile application, Up: Org Mobile - -17.18.3 Pulling from the mobile application -------------------------------------------- - -The command ‘org-mobile-pull’ synchronizes changes with the server. -More specifically, it first pulls the Org files for viewing. It then -appends captured entries and pointers to flagged or changed entries to -the file ‘mobileorg.org’ on the server. Org ultimately integrates its -data in an inbox file format, through the following steps: - - 1. Org moves all entries found in ‘mobileorg.org’(1) and appends them - to the file pointed to by the variable ‘org-mobile-inbox-for-pull’. - It should reside neither in the staging area nor on the server. - Each captured entry and each editing event is a top-level entry in - the inbox file. - - 2. After moving the entries, Org processes changes to the shared - files. Some of them are applied directly and without user - interaction. Examples include changes to tags, TODO state, - headline and body text. Entries requiring further action are - tagged as ‘FLAGGED’. Org marks entries with problems with an error - message in the inbox. They have to be resolved manually. - - 3. Org generates an agenda view for flagged entries for user - intervention to clean up. For notes stored in flagged entries, Org - displays them in the echo area when point is on the corresponding - agenda item. - - ‘?’ - Pressing ‘?’ displays the entire flagged note in another - window. Org also pushes it to the kill ring. To store - flagged note as a normal note, use ‘? z C-y C-c C-c’. - Pressing ‘?’ twice does these things: first it removes the - ‘FLAGGED’ tag; second, it removes the flagged note from the - property drawer; third, it signals that manual editing of the - flagged entry is now finished. - - From the agenda dispatcher, ‘?’ returns to the view to finish -processing flagged entries. Note that these entries may not be the most -recent since the mobile application searches files that were last -pulled. To get an updated agenda view with changes since the last pull, -pull again. - - ---------- Footnotes ---------- - - (1) The file will be empty after this operation. - - -File: org.info, Node: Hacking, Next: History and Acknowledgments, Prev: Miscellaneous, Up: Top - -Appendix A Hacking -****************** - -This appendix describes some ways a user can extend the functionality of -Org. - -* Menu: - -* Hooks:: How to reach into Org’s internals. -* Add-on Packages:: Available extensions. -* Adding Hyperlink Types:: New custom link types. -* Adding Export Back-ends:: How to write new export back-ends. -* Tables in Arbitrary Syntax:: Orgtbl for LaTeX and other programs. -* Dynamic Blocks:: Automatically filled blocks. -* Special Agenda Views:: Customized views. -* Speeding Up Your Agendas:: Tips on how to speed up your agendas. -* Extracting Agenda Information:: Post-processing agenda information. -* Using the Property API:: Writing programs that use entry properties. -* Using the Mapping API:: Mapping over all or selected entries. - - -File: org.info, Node: Hooks, Next: Add-on Packages, Up: Hacking - -A.1 Hooks -========= - -Org has a large number of hook variables for adding functionality. This -appendix illustrates using a few. A complete list of hooks with -documentation is maintained by the Worg project at -<https://orgmode.org/worg/doc.html#hooks>. - - -File: org.info, Node: Add-on Packages, Next: Adding Hyperlink Types, Prev: Hooks, Up: Hacking - -A.2 Add-on Packages -=================== - -Various authors wrote a large number of add-on packages for Org. Some -of these packages used to be part of the ‘org-mode’ repository but are -now hosted in a separate ‘org-contrib’ repository here -(https://git.sr.ht/~bzg/org-contrib). A Worg page with more information -is at: <https://orgmode.org/worg/org-contrib/>. - - -File: org.info, Node: Adding Hyperlink Types, Next: Adding Export Back-ends, Prev: Add-on Packages, Up: Hacking - -A.3 Adding Hyperlink Types -========================== - -Org has many built-in hyperlink types (see *note Hyperlinks::), and an -interface for adding new link types. The following example shows the -process of adding Org links to Unix man pages, which look like this - - [[man:printf][The printf manual]] - -The following ‘ol-man.el’ file implements it - - ;;; ol-man.el - Support for links to man pages in Org mode - (require 'ol) - - (org-link-set-parameters "man" - :follow #'org-man-open - :export #'org-man-export - :store #'org-man-store-link) - - (defcustom org-man-command 'man - "The Emacs command to be used to display a man page." - :group 'org-link - :type '(choice (const man) (const woman))) - - (defun org-man-open (path _) - "Visit the manpage on PATH. - PATH should be a topic that can be thrown at the man command." - (funcall org-man-command path)) - - (defun org-man-store-link () - "Store a link to a man page." - (when (memq major-mode '(Man-mode woman-mode)) - ;; This is a man page, we do make this link. - (let* ((page (org-man-get-page-name)) - (link (concat "man:" page)) - (description (format "Man page for %s" page))) - (org-link-store-props - :type "man" - :link link - :description description)))) - - (defun org-man-get-page-name () - "Extract the page name from the buffer name." - ;; This works for both `Man-mode' and `woman-mode'. - (if (string-match " \\(\\S-+\\)\\*" (buffer-name)) - (match-string 1 (buffer-name)) - (error "Cannot create link to this man page"))) - - (defun org-man-export (link description format _) - "Export a man page link from Org files." - (let ((path (format "http://man.he.net/?topic=%s§ion=all" link)) - (desc (or description link))) - (pcase format - (`html (format "<a target=\"_blank\" href=\"%s\">%s</a>" path desc)) - (`latex (format "\\href{%s}{%s}" path desc)) - (`texinfo (format "@uref{%s,%s}" path desc)) - (`ascii (format "%s (%s)" desc path)) - (t path)))) - - (provide ol-man) - ;;; ol-man.el ends here - -To activate links to man pages in Org, enter this in the Emacs init -file: - - (require 'ol-man) - -A review of ‘ol-man.el’: - - 1. First, ‘(require 'ol)’ ensures that ‘ol.el’ is loaded. - - 2. Then ‘org-link-set-parameters’ defines a new link type with ‘man’ - prefix and associates functions for following, exporting and - storing such links. See the variable ‘org-link-parameters’ for a - complete list of possible associations. - - 3. The rest of the file implements necessary variables and functions. - - For example, ‘org-man-store-link’ is responsible for storing a link - when ‘org-store-link’ (see *note Handling Links::) is called from a - buffer displaying a man page. It first checks if the major mode is - appropriate. If check fails, the function returns ‘nil’, which - means it isn’t responsible for creating a link to the current - buffer. Otherwise the function makes a link string by combining - the ‘man:’ prefix with the man topic. It also provides a default - description. The function ‘org-insert-link’ can insert it back - into an Org buffer later on. - - -File: org.info, Node: Adding Export Back-ends, Next: Tables in Arbitrary Syntax, Prev: Adding Hyperlink Types, Up: Hacking - -A.4 Adding Export Back-ends -=========================== - -Org’s export engine makes it easy for writing new back-ends. The -framework on which the engine was built makes it easy to derive new -back-ends from existing ones. - - The two main entry points to the export engine are: -‘org-export-define-backend’ and ‘org-export-define-derived-backend’. To -grok these functions, see ‘ox-latex.el’ for an example of defining a new -back-end from scratch, and ‘ox-beamer.el’ for an example of deriving -from an existing engine. - - For creating a new back-end from scratch, first set its name as a -symbol in an alist consisting of elements and export functions. To make -the back-end visible to the export dispatcher, set ‘:menu-entry’ -keyword. For export options specific to this back-end, set the -‘:options-alist’. - - For creating a new back-end from an existing one, set -‘:translate-alist’ to an alist of export functions. This alist replaces -the parent back-end functions. - - For complete documentation, see the Org Export Reference on Worg -(https://orgmode.org/worg/dev/org-export-reference.html). - - -File: org.info, Node: Tables in Arbitrary Syntax, Next: Dynamic Blocks, Prev: Adding Export Back-ends, Up: Hacking - -A.5 Tables in Arbitrary Syntax -============================== - -Due to Org’s success in handling tables with Orgtbl, a frequently -requested feature is the use of Org’s table functions in other modes, -e.g., LaTeX. This would be hard to do in a general way without -complicated customization nightmares. Moreover, that would take Org -away from its simplicity roots that Orgtbl has proven. There is, -however, an alternate approach to accomplishing the same. - - This approach involves implementing a custom _translate_ function -that operates on a native Org _source table_ to produce a table in -another format. This strategy would keep the excellently working Orgtbl -simple and isolate complications, if any, confined to the translate -function. To add more alien table formats, we just add more translate -functions. Also the burden of developing custom translate functions for -new table formats is in the hands of those who know those formats best. - -* Menu: - -* Radio tables:: Sending and receiving radio tables. -* A LaTeX example:: Step by step, almost a tutorial. -* Translator functions:: Copy and modify. - - -File: org.info, Node: Radio tables, Next: A LaTeX example, Up: Tables in Arbitrary Syntax - -A.5.1 Radio tables ------------------- - -Radio tables are target locations for translated tables that are not -near their source. Org finds the target location and inserts the -translated table. - - The key to finding the target location is the magic words ‘BEGIN/END -RECEIVE ORGTBL’. They have to appear as comments in the current mode. -If the mode is C, then: - - /* BEGIN RECEIVE ORGTBL table_name */ - /* END RECEIVE ORGTBL table_name */ - - At the location of source, Org needs a special line to direct Orgtbl -to translate and to find the target for inserting the translated table. -For example: - - #+ORGTBL: SEND table_name translation_function arguments ... - -‘table_name’ is the table’s reference name, which is also used in the -receiver lines, and the ‘translation_function’ is the Lisp function that -translates. This line, in addition, may also contain alternating key -and value arguments at the end. The translation function gets these -values as a property list. A few standard parameters are already -recognized and acted upon before the translation function is called: - -‘:skip N’ - Skip the first N lines of the table. Hlines do count; include them - if they are to be skipped. - -‘:skipcols (n1 n2 ...)’ - List of columns to be skipped. First Org automatically discards - columns with calculation marks and then sends the table to the - translator function, which then skips columns as specified in - ‘skipcols’. - - To keep the source table intact in the buffer without being disturbed -when the source file is compiled or otherwise being worked on, use one -of these strategies: - - • Place the table in a block comment. For example, in C mode you - could wrap the table between ‘/*’ and ‘*/’ lines. - - • Put the table after an “end” statement. For example ‘\bye’ in TeX - and ‘\end{document}’ in LaTeX. - - • Comment and un-comment each line of the table during edits. The - ‘M-x orgtbl-toggle-comment’ command makes toggling easy. - - -File: org.info, Node: A LaTeX example, Next: Translator functions, Prev: Radio tables, Up: Tables in Arbitrary Syntax - -A.5.2 A LaTeX example of radio tables -------------------------------------- - -To wrap a source table in LaTeX, use the ‘comment’ environment provided -by ‘comment.sty’(1). To activate it, put ‘\usepackage{comment}’ in the -document header. Orgtbl mode inserts a radio table skeleton(2) with the -command ‘M-x orgtbl-insert-radio-table’, which prompts for a table name. -For example, if ‘salesfigures’ is the name, the template inserts: - - % BEGIN RECEIVE ORGTBL salesfigures - % END RECEIVE ORGTBL salesfigures - \begin{comment} - #+ORGTBL: SEND salesfigures orgtbl-to-latex - | | | - \end{comment} - -The line ‘#+ORGTBL: SEND’ tells Orgtbl mode to use the function -‘orgtbl-to-latex’ to convert the table to LaTeX format, then insert the -table at the target (receive) location named ‘salesfigures’. Now the -table is ready for data entry. It can even use spreadsheet features(3): - - % BEGIN RECEIVE ORGTBL salesfigures - % END RECEIVE ORGTBL salesfigures - \begin{comment} - #+ORGTBL: SEND salesfigures orgtbl-to-latex - | Month | Days | Nr sold | per day | - |-------+------+---------+---------| - | Jan | 23 | 55 | 2.4 | - | Feb | 21 | 16 | 0.8 | - | March | 22 | 278 | 12.6 | - #+TBLFM: $4=$3/$2;%.1f - % $ (optional extra dollar to keep Font Lock happy, see footnote) - \end{comment} - - After editing, ‘C-c C-c’ inserts the translated table at the target -location, between the two marker lines. - - For hand-made custom tables, note that the translator needs to skip -the first two lines of the source table. Also the command has to -_splice_ out the target table without the header and footer. - - \begin{tabular}{lrrr} - Month & \multicolumn{1}{c}{Days} & Nr.\ sold & per day\\ - % BEGIN RECEIVE ORGTBL salesfigures - % END RECEIVE ORGTBL salesfigures - \end{tabular} - % - \begin{comment} - #+ORGTBL: SEND salesfigures orgtbl-to-latex :splice t :skip 2 - | Month | Days | Nr sold | per day | - |-------+------+---------+---------| - | Jan | 23 | 55 | 2.4 | - | Feb | 21 | 16 | 0.8 | - | March | 22 | 278 | 12.6 | - #+TBLFM: $4=$3/$2;%.1f - \end{comment} - - The LaTeX translator function ‘orgtbl-to-latex’ is already part of -Orgtbl mode and uses a ‘tabular’ environment to typeset the table and -marks horizontal lines with ‘\hline’. For additional parameters to -control output, see *note Translator functions::: - -‘:splice BOOLEAN’ - When {{{var(BOOLEAN}}} is non-‘nil’, return only table body lines; - i.e., not wrapped in ‘tabular’ environment. Default is ‘nil’. - -‘:fmt FMT’ - Format string to warp each field. It should contain ‘%s’ for the - original field value. For example, to wrap each field value in - dollar symbol, you could use ‘:fmt "$%s$"’. Format can also wrap a - property list with column numbers and formats, for example ‘:fmt (2 - "$%s$" 4 "%s\\%%")’. In place of a string, a function of one - argument can be used; the function must return a formatted string. - -‘:efmt EFMT’ - Format numbers as exponentials. The spec should have ‘%s’ twice - for inserting mantissa and exponent, for example - ‘"%s\\times10^{%s}"’. This may also be a property list with column - numbers and formats, for example ‘:efmt (2 "$%s\\times10^{%s}$" 4 - "$%s\\cdot10^{%s}$")’. After EFMT has been applied to a value, - FMT—see above—is also applied. Functions with two arguments can be - supplied instead of strings. By default, no special formatting is - applied. - - ---------- Footnotes ---------- - - (1) <https://www.ctan.org/pkg/comment> - - (2) By default this works only for LaTeX, HTML, and Texinfo. -Configure the variable ‘orgtbl-radio-table-templates’ to install -templates for other modes. - - (3) If the ‘TBLFM’ keyword contains an odd number of dollar -characters, this may cause problems with Font Lock in LaTeX mode. As -shown in the example you can fix this by adding an extra line inside the -‘comment’ environment that is used to balance the dollar expressions. -If you are using AUCTeX with the font-latex library, a much better -solution is to add the ‘comment’ environment to the variable -‘LaTeX-verbatim-environments’. - - -File: org.info, Node: Translator functions, Prev: A LaTeX example, Up: Tables in Arbitrary Syntax - -A.5.3 Translator functions --------------------------- - -Orgtbl mode has built-in translator functions: ‘orgtbl-to-csv’ -(comma-separated values), ‘orgtbl-to-tsv’ (TAB-separated values), -‘orgtbl-to-latex’, ‘orgtbl-to-html’, ‘orgtbl-to-texinfo’, -‘orgtbl-to-unicode’ and ‘orgtbl-to-orgtbl’. They use the generic -translator, ‘orgtbl-to-generic’, which delegates translations to various -export back-ends. - - Properties passed to the function through the ‘ORGTBL SEND’ line take -precedence over properties defined inside the function. For example, -this overrides the default LaTeX line endings, ‘\\’, with ‘\\[2mm]’: - - #+ORGTBL: SEND test orgtbl-to-latex :lend " \\\\[2mm]" - - For a new language translator, define a converter function. It can -be a generic function, such as shown in this example. It marks a -beginning and ending of a table with ‘!BTBL!’ and ‘!ETBL!’; a beginning -and ending of lines with ‘!BL!’ and ‘!EL!’; and uses a TAB for a field -separator: - - (defun orgtbl-to-language (table params) - "Convert the orgtbl-mode TABLE to language." - (orgtbl-to-generic - table - (org-combine-plists - '(:tstart "!BTBL!" :tend "!ETBL!" :lstart "!BL!" :lend "!EL!" :sep "\t") - params))) - -The documentation for the ‘orgtbl-to-generic’ function shows a complete -list of parameters, each of which can be passed through to -‘orgtbl-to-latex’, ‘orgtbl-to-texinfo’, and any other function using -that generic function. - - For complicated translations the generic translator function could be -replaced by a custom translator function. Such a custom function must -take two arguments and return a single string containing the formatted -table. The first argument is the table whose lines are a list of fields -or the symbol ‘hline’. The second argument is the property list -consisting of parameters specified in the ‘#+ORGTBL: SEND’ line. Please -share your translator functions by posting them to the Org users mailing -list, at <emacs-orgmode@gnu.org>. - - -File: org.info, Node: Dynamic Blocks, Next: Special Agenda Views, Prev: Tables in Arbitrary Syntax, Up: Hacking - -A.6 Dynamic Blocks -================== - -Org supports _dynamic blocks_ in Org documents. They are inserted with -begin and end markers like any other code block, but the contents are -updated automatically by a user function. - - You can insert a dynamic block with -‘org-dynamic-block-insert-dblock’, which is bound to ‘C-c C-x x’ by -default. For example, ‘C-c C-x x c l o c k t a b l e <RET>’ inserts a -table that updates the work time (see *note Clocking Work Time::). - - Dynamic blocks can have names and function parameters. The syntax is -similar to source code block specifications: - - #+BEGIN: myblock :parameter1 value1 :parameter2 value2 ... - ... - #+END: - - These commands update dynamic blocks: - -‘C-c C-x C-u’ (‘org-dblock-update’) - Update dynamic block at point. - -‘C-u C-c C-x C-u’ - Update all dynamic blocks in the current file. - - Before updating a dynamic block, Org removes content between the -‘BEGIN’ and ‘END’ markers. Org then reads the parameters on the ‘BEGIN’ -line for passing to the writer function as a plist. The previous -content of the dynamic block becomes erased from the buffer and appended -to the plist under ‘:content’. - - The syntax for naming a writer function with a dynamic block labeled -‘myblock’ is: ‘org-dblock-write:myblock’. - - The following is an example of a dynamic block and a block writer -function that updates the time when the function was last run: - - #+BEGIN: block-update-time :format "on %m/%d/%Y at %H:%M" - ... - #+END: - -The dynamic block’s writer function: - - (defun org-dblock-write:block-update-time (params) - (let ((fmt (or (plist-get params :format) "%d. %m. %Y"))) - (insert "Last block update at: " - (format-time-string fmt)))) - - To keep dynamic blocks up-to-date in an Org file, use the function, -‘org-update-all-dblocks’ in hook, such as ‘before-save-hook’. The -‘org-update-all-dblocks’ function does not run if the file is not in Org -mode. - - Dynamic blocks, like any other block, can be narrowed with -‘org-narrow-to-block’. - - -File: org.info, Node: Special Agenda Views, Next: Speeding Up Your Agendas, Prev: Dynamic Blocks, Up: Hacking - -A.7 Special Agenda Views -======================== - -Org provides a special hook to further limit items in agenda views: -‘agenda’, ‘agenda*’(1), ‘todo’, ‘alltodo’, ‘tags’, ‘tags-todo’, -‘tags-tree’. Specify a custom function that tests inclusion of every -matched item in the view. This function can also skip as much as is -needed. - - For a global condition applicable to agenda views, use the -‘org-agenda-skip-function-global’ variable. Org uses a global condition -with ‘org-agenda-skip-function’ for custom searching. - - This example defines a function for a custom view showing TODO items -with ‘waiting’ status. Manually this is a multi-step search process, -but with a custom view, this can be automated as follows: - - The custom function searches the subtree for the ‘waiting’ tag and -returns ‘nil’ on match. Otherwise it gives the location from where the -search continues. - - (defun my-skip-unless-waiting () - "Skip trees that are not waiting" - (let ((subtree-end (save-excursion (org-end-of-subtree t)))) - (if (re-search-forward ":waiting:" subtree-end t) - nil ; tag found, do not skip - subtree-end))) ; tag not found, continue after end of subtree - - To use this custom function in a custom agenda command: - - (org-add-agenda-custom-command - '("b" todo "PROJECT" - ((org-agenda-skip-function 'my-skip-unless-waiting) - (org-agenda-overriding-header "Projects waiting for something: ")))) - - Note that this also binds ‘org-agenda-overriding-header’ to a more -meaningful string suitable for the agenda view. - - Search for entries with a limit set on levels for the custom search. -This is a general approach to creating custom searches in Org. To -include all levels, use ‘LEVEL>0’(2). Then to selectively pick the -matched entries, use ‘org-agenda-skip-function’, which also accepts Lisp -forms, such as ‘org-agenda-skip-entry-if’ and -‘org-agenda-skip-subtree-if’. For example: - -‘(org-agenda-skip-entry-if 'scheduled)’ - Skip current entry if it has been scheduled. - -‘(org-agenda-skip-entry-if 'notscheduled)’ - Skip current entry if it has not been scheduled. - -‘(org-agenda-skip-entry-if 'deadline)’ - Skip current entry if it has a deadline. - -‘(org-agenda-skip-entry-if 'scheduled 'deadline)’ - Skip current entry if it has a deadline, or if it is scheduled. - -‘(org-agenda-skip-entry-if 'todo '("TODO" "WAITING"))’ - Skip current entry if the TODO keyword is TODO or WAITING. - -‘(org-agenda-skip-entry-if 'todo 'done)’ - Skip current entry if the TODO keyword marks a DONE state. - -‘(org-agenda-skip-entry-if 'timestamp)’ - Skip current entry if it has any timestamp, may also be deadline or - scheduled. - -‘(org-agenda-skip-entry-if 'regexp "regular expression")’ - Skip current entry if the regular expression matches in the entry. - -‘(org-agenda-skip-entry-if 'notregexp "regular expression")’ - Skip current entry unless the regular expression matches. - -‘(org-agenda-skip-subtree-if 'regexp "regular expression")’ - Same as above, but check and skip the entire subtree. - - The following is an example of a search for ‘waiting’ without the -special function: - - (org-add-agenda-custom-command - '("b" todo "PROJECT" - ((org-agenda-skip-function '(org-agenda-skip-subtree-if - 'regexp ":waiting:")) - (org-agenda-overriding-header "Projects waiting for something: ")))) - - ---------- Footnotes ---------- - - (1) The ‘agenda*’ view is the same as ‘agenda’ except that it only -considers _appointments_, i.e., scheduled and deadline items that have a -time specification ‘[h]h:mm’ in their time-stamps. - - (2) Note that, for ‘org-odd-levels-only’, a level number corresponds -to order in the hierarchy, not to the number of stars. - - -File: org.info, Node: Speeding Up Your Agendas, Next: Extracting Agenda Information, Prev: Special Agenda Views, Up: Hacking - -A.8 Speeding Up Your Agendas -============================ - -Some agenda commands slow down when the Org files grow in size or -number. Here are tips to speed up: - - • Reduce the number of Org agenda files to avoid slowdowns due to - hard drive accesses. - - • Reduce the number of DONE and archived headlines so agenda - operations that skip over these can finish faster. - - • Do not dim blocked tasks: - - (setq org-agenda-dim-blocked-tasks nil) - - • Stop preparing agenda buffers on startup: - - (setq org-agenda-inhibit-startup t) - - • Disable tag inheritance for agendas: - - (setq org-agenda-use-tag-inheritance nil) - - These options can be applied to selected agenda views. For more -details about generation of agenda views, see the docstrings for the -relevant variables, and this dedicated Worg page -(https://orgmode.org/worg/agenda-optimization.html) for agenda -optimization. - - -File: org.info, Node: Extracting Agenda Information, Next: Using the Property API, Prev: Speeding Up Your Agendas, Up: Hacking - -A.9 Extracting Agenda Information -================================= - -Org provides commands to access agendas through Emacs batch mode. -Through this command-line interface, agendas are automated for further -processing or printing. - - ‘org-batch-agenda’ creates an agenda view in ASCII and outputs to -standard output. This command takes one string parameter. When string -consists of a single character, Org uses it as a key to -‘org-agenda-custom-commands’. These are the same ones available through -the agenda dispatcher (see *note Agenda Dispatcher::). - - This example command line directly prints the TODO list to the -printer: - - emacs -batch -l ~/.emacs -eval '(org-batch-agenda "t")' | lpr - - When the string parameter length is two or more characters, Org -matches it with tags/TODO strings. For example, this example command -line prints items tagged with ‘shop’, but excludes items tagged with -‘NewYork’: - - emacs -batch -l ~/.emacs \ - -eval '(org-batch-agenda "+shop-NewYork")' | lpr - -An example showing on-the-fly parameter modifications: - - emacs -batch -l ~/.emacs \ - -eval '(org-batch-agenda "a" \ - org-agenda-span (quote month) \ - org-agenda-include-diary nil \ - org-agenda-files (quote ("~/org/project.org")))' \ - | lpr - -which produces an agenda for the next 30 days from just the -‘~/org/projects.org’ file. - - For structured processing of agenda output, use -‘org-batch-agenda-csv’ with the following fields: - -category - The category of the item -head - The headline, without TODO keyword, TAGS and PRIORITY -type - The type of the agenda entry, can be - - ‘todo’ selected in TODO match - ‘tagsmatch’ selected in tags match - ‘diary’ imported from diary - ‘deadline’ a deadline - ‘scheduled’ scheduled - ‘timestamp’ appointment, selected by timestamp - ‘closed’ entry was closed on date - ‘upcoming-deadline’ warning about nearing deadline - ‘past-scheduled’ forwarded scheduled item - ‘block’ entry has date block including date - -todo - The TODO keyword, if any -tags - All tags including inherited ones, separated by colons -date - The relevant date, like ‘2007-2-14’ -time - The time, like ‘15:00-16:50’ -extra - String with extra planning info -priority-l - The priority letter if any was given -priority-n - The computed numerical priority - - If the selection of the agenda item was based on a timestamp, -including those items with ‘DEADLINE’ and ‘SCHEDULED’ keywords, then Org -includes date and time in the output. - - If the selection of the agenda item was based on a timestamp (or -deadline/scheduled), then Org includes date and time in the output. - - Here is an example of a post-processing script in Perl. It takes the -CSV output from Emacs and prints with a checkbox: - - #!/usr/bin/perl - - # define the Emacs command to run - $cmd = "emacs -batch -l ~/.emacs -eval '(org-batch-agenda-csv \"t\")'"; - - # run it and capture the output - $agenda = qx{$cmd 2>/dev/null}; - - # loop over all lines - foreach $line (split(/\n/,$agenda)) { - # get the individual values - ($category,$head,$type,$todo,$tags,$date,$time,$extra, - $priority_l,$priority_n) = split(/,/,$line); - # process and print - print "[ ] $head\n"; - } - - -File: org.info, Node: Using the Property API, Next: Using the Mapping API, Prev: Extracting Agenda Information, Up: Hacking - -A.10 Using the Property API -=========================== - -Here is a description of the functions that can be used to work with -properties. - - -- Function: org-entry-properties &optional pom which - Get all properties of the entry at point-or-marker POM. This - includes the TODO keyword, the tags, time strings for deadline, - scheduled, and clocking, and any additional properties defined in - the entry. The return value is an alist. Keys may occur multiple - times if the property key was used several times. POM may also be - ‘nil’, in which case the current entry is used. If WHICH is ‘nil’ - or ‘all’, get all properties. If WHICH is ‘special’ or ‘standard’, - only get that subclass. - - -- Function: org-entry-get pom property &optional inherit - Get value of PROPERTY for entry at point-or-marker POM. By - default, this only looks at properties defined locally in the - entry. If INHERIT is non-‘nil’ and the entry does not have the - property, then also check higher levels of the hierarchy. If - INHERIT is the symbol ‘selective’, use inheritance if and only if - the setting of ‘org-use-property-inheritance’ selects PROPERTY for - inheritance. - - -- Function: org-entry-delete pom property - Delete the property PROPERTY from entry at point-or-marker POM. - - -- Function: org-entry-put pom property value - Set PROPERTY to VALUES for entry at point-or-marker POM. - - -- Function: org-buffer-property-keys &optional include-specials - Get all property keys in the current buffer. - - -- Function: org-insert-property-drawer - Insert a property drawer for the current entry. Also - - -- Function: org-entry-put-multivalued-property pom property &rest - values - Set PROPERTY at point-or-marker POM to VALUES. VALUES should be a - list of strings. They are concatenated, with spaces as separators. - - -- Function: org-entry-get-multivalued-property pom property - Treat the value of the property PROPERTY as a whitespace-separated - list of values and return the values as a list of strings. - - -- Function: org-entry-add-to-multivalued-property pom property value - Treat the value of the property PROPERTY as a whitespace-separated - list of values and make sure that VALUE is in this list. - - -- Function: org-entry-remove-from-multivalued-property pom property - value - Treat the value of the property PROPERTY as a whitespace-separated - list of values and make sure that VALUE is _not_ in this list. - - -- Function: org-entry-member-in-multivalued-property pom property - value - Treat the value of the property PROPERTY as a whitespace-separated - list of values and check if VALUE is in this list. - - -- User Option: org-property-allowed-value-functions - Hook for functions supplying allowed values for a specific - property. The functions must take a single argument, the name of - the property, and return a flat list of allowed values. If ‘:ETC’ - is one of the values, use the values as completion help, but allow - also other values to be entered. The functions must return ‘nil’ - if they are not responsible for this property. - - -File: org.info, Node: Using the Mapping API, Prev: Using the Property API, Up: Hacking - -A.11 Using the Mapping API -========================== - -Org has sophisticated mapping capabilities to find all entries -satisfying certain criteria. Internally, this functionality is used to -produce agenda views, but there is also an API that can be used to -execute arbitrary functions for each or selected entries. The main -entry point for this API is: - - -- Function: org-map-entries func &optional match scope &rest skip - Call FUNC at each headline selected by MATCH in SCOPE. - - FUNC is a function or a Lisp form. With point positioned at the - beginning of the headline, call the function without arguments. - Org returns an alist of return values of calls to the function. - - To avoid preserving point, Org wraps the call to FUNC in - ‘save-excursion’ form. After evaluation, Org moves point to the - end of the line that was just processed. Search continues from - that point forward. This may not always work as expected under - some conditions, such as if the current sub-tree was removed by a - previous archiving operation. In such rare circumstances, Org - skips the next entry entirely when it should not. To stop Org from - such skips, make FUNC set the variable ‘org-map-continue-from’ to a - specific buffer position. - - MATCH is a tags/property/TODO match. Org iterates only matched - headlines. Org iterates over all headlines when MATCH is ‘nil’ or - ‘t’. - - SCOPE determines the scope of this command. It can be any of: - - ‘nil’ - The current buffer, respecting the restriction, if any. - - ‘tree’ - The subtree started with the entry at point. - - ‘region’ - The entries within the active region, if any. - - ‘file’ - The current buffer, without restriction. - - ‘file-with-archives’ - The current buffer, and any archives associated with it. - - ‘agenda’ - All agenda files. - - ‘agenda-with-archives’ - All agenda files with any archive files associated with them. - - list of filenames - If this is a list, all files in the list are scanned. - - The remaining arguments are treated as settings for the scanner’s - skipping facilities. Valid arguments are: - - ‘archive’ - Skip trees with the ‘ARCHIVE’ tag. - - ‘comment’ - Skip trees with the COMMENT keyword. - - function or Lisp form - Used as value for ‘org-agenda-skip-function’, so whenever the - function returns ‘t’, FUNC is called for that entry and search - continues from the point where the function leaves it. - - The mapping routine can call any arbitrary function, even functions -that change meta data or query the property API (see *note Using the -Property API::). Here are some handy functions: - - -- Function: org-todo &optional arg - Change the TODO state of the entry. See the docstring of the - functions for the many possible values for the argument ARG. - - -- Function: org-priority &optional action - Change the priority of the entry. See the docstring of this - function for the possible values for ACTION. - - -- Function: org-toggle-tag tag &optional onoff - Toggle the tag TAG in the current entry. Setting ONOFF to either - ‘on’ or ‘off’ does not toggle tag, but ensure that it is either on - or off. - - -- Function: org-promote - Promote the current entry. - - -- Function: org-demote - Demote the current entry. - - This example turns all entries tagged with ‘TOMORROW’ into TODO -entries with keyword ‘UPCOMING’. Org ignores entries in comment trees -and archive trees. - - (org-map-entries '(org-todo "UPCOMING") - "+TOMORROW" 'file 'archive 'comment) - - The following example counts the number of entries with TODO keyword -‘WAITING’, in all agenda files. - - (length (org-map-entries t "/+WAITING" 'agenda)) - - -File: org.info, Node: History and Acknowledgments, Next: GNU Free Documentation License, Prev: Hacking, Up: Top - -Appendix B History and Acknowledgments -************************************** - -B.1 From Carsten -================ - -Org was born in 2003, out of frustration over the user interface of the -Emacs Outline mode. I was trying to organize my notes and projects, and -using Emacs seemed to be the natural way to go. However, having to -remember eleven different commands with two or three keys per command, -only to hide and show parts of the outline tree, that seemed entirely -unacceptable to me. Also, when using outlines to take notes, I -constantly wanted to restructure the tree, organizing it parallel to my -thoughts and plans. _Visibility cycling_ and _structure editing_ were -originally implemented in the package ‘outline-magic.el’, but quickly -moved to the more general ‘org.el’. As this environment became -comfortable for project planning, the next step was adding _TODO -entries_, basic _timestamps_, and _table support_. These areas -highlighted the two main goals that Org still has today: to be a new, -outline-based, plain text mode with innovative and intuitive editing -features, and to incorporate project planning functionality directly -into a notes file. - - Since the first release, literally thousands of emails to me or to -the mailing list <emacs-orgmode@gnu.org> have provided a constant stream -of bug reports, feedback, new ideas, and sometimes patches and add-on -code. Many thanks to everyone who has helped to improve this package. -I am trying to keep here a list of the people who had significant -influence in shaping one or more aspects of Org. The list may not be -complete, if I have forgotten someone, please accept my apologies and -let me know. - - Before I get to this list, a few special mentions are in order: - -Bastien Guerry - Bastien has written a large number of extensions to Org (most of - them integrated into the core by now), including the LaTeX exporter - and the plain list parser. His support during the early days was - central to the success of this project. Bastien also invented - Worg, helped establishing the Web presence of Org, and sponsored - hosting costs for the orgmode.org website. Bastien stepped in as - maintainer of Org between 2011 and 2013, at a time when I - desperately needed a break. - -Eric Schulte and Dan Davison - Eric and Dan are jointly responsible for the Org Babel system, - which turns Org into a multi-language environment for evaluating - code and doing literate programming and reproducible research. - This has become one of Org’s killer features that define what Org - is today. - -John Wiegley - John has contributed a number of great ideas and patches directly - to Org, including the attachment system (‘org-attach.el’), - integration with Apple Mail (‘org-mac-message.el’), hierarchical - dependencies of TODO items, habit tracking (‘org-habits.el’), and - encryption (‘org-crypt.el’). Also, the capture system is really an - extended copy of his great ‘remember.el’. - -Sebastian Rose - Without Sebastian, the HTML/XHTML publishing of Org would be the - pitiful work of an ignorant amateur. Sebastian has pushed this - part of Org onto a much higher level. He also wrote ‘org-info.js’, - a JavaScript program for displaying webpages derived from Org using - an Info-like or a folding interface with single-key navigation. - - See below for the full list of contributions! Again, please let me -know what I am missing here! - -B.2 From Bastien -================ - -I (Bastien) have been maintaining Org between 2011 and 2013. This -appendix would not be complete without adding a few more acknowledgments -and thanks. - - I am first grateful to Carsten for his trust while handing me over -the maintainership of Org. His unremitting support is what really -helped me getting more confident over time, with both the community and -the code. - - When I took over maintainership, I knew I would have to make Org more -collaborative than ever, as I would have to rely on people that are more -knowledgeable than I am on many parts of the code. Here is a list of -the persons I could rely on, they should really be considered -co-maintainers, either of the code or the community: - -Eric Schulte - Eric is maintaining the Babel parts of Org. His reactivity here - kept me away from worrying about possible bugs here and let me - focus on other parts. - -Nicolas Goaziou - Nicolas is maintaining the consistency of the deepest parts of Org. - His work on ‘org-element.el’ and ‘ox.el’ has been outstanding, and - it opened the doors for many new ideas and features. He rewrote - many of the old exporters to use the new export engine, and helped - with documenting this major change. More importantly (if that’s - possible), he has been more than reliable during all the work done - for Org 8.0, and always very reactive on the mailing list. - -Achim Gratz - Achim rewrote the building process of Org, turning some _ad hoc_ - tools into a flexible and conceptually clean process. He patiently - coped with the many hiccups that such a change can create for - users. - -Nick Dokos - The Org mode mailing list would not be such a nice place without - Nick, who patiently helped users so many times. It is impossible - to overestimate such a great help, and the list would not be so - active without him. - - I received support from so many users that it is clearly impossible -to be fair when shortlisting a few of them, but Org’s history would not -be complete if the ones above were not mentioned in this manual. - -B.3 List of Contributions -========================= - - • Russell Adams came up with the idea for drawers. - - • Thomas Baumann wrote ‘ol-bbdb.el’ and ‘ol-mhe.el’. - - • Christophe Bataillon created the great unicorn logo that we use on - the Org mode website. - - • Alex Bochannek provided a patch for rounding timestamps. - - • Jan Böcker wrote ‘ol-docview.el’. - - • Brad Bozarth showed how to pull RSS feed data into Org files. - - • Tom Breton wrote ‘org-choose.el’. - - • Charles Cave’s suggestion sparked the implementation of templates - for Remember, which are now templates for capture. - - • Timothy E Chapman worked on a complete overhaul of the orgmode.org - website in 2020 and helped fixing various bugs. - - • Pavel Chalmoviansky influenced the agenda treatment of items with - specified time. - - • Gregory Chernov patched support for Lisp forms into table - calculations and improved XEmacs compatibility, in particular by - porting ‘nouline.el’ to XEmacs. - - • Sacha Chua suggested copying some linking code from Planner. - - • Baoqiu Cui contributed the DocBook exporter. - - • Eddward DeVilla proposed and tested checkbox statistics. He also - came up with the idea of properties, and that there should be an - API for them. - - • Nick Dokos tracked down several nasty bugs. - - • Kees Dullemond used to edit projects lists directly in HTML and so - inspired some of the early development, including HTML export. He - also asked for a way to narrow wide table columns. - - • Thomas S. Dye contributed documentation on Worg and helped - integrating the Org Babel documentation into the manual. - - • Christian Egli converted the documentation into Texinfo format, - inspired the agenda, patched CSS formatting into the HTML exporter, - and wrote ‘org-taskjuggler.el’. - - • David Emery provided a patch for custom CSS support in exported - HTML agendas. - - • Nic Ferrier contributed mailcap and XOXO support. - - • Miguel A. Figueroa-Villanueva implemented hierarchical checkboxes. - - • John Foerch figured out how to make incremental search show context - around a match in a hidden outline tree. - - • Raimar Finken wrote ‘org-git-line.el’. - - • Mikael Fornius works as a mailing list moderator. - - • Austin Frank works as a mailing list moderator. - - • Eric Fraga drove the development of Beamer export with ideas and - testing. - - • Barry Gidden did proofreading the manual in preparation for the - book publication through Network Theory Ltd. - - • Niels Giesen had the idea to automatically archive DONE trees. - - • Nicolas Goaziou rewrote much of the plain list code. - - • Kai Grossjohann pointed out key-binding conflicts with other - packages. - - • Brian Gough of Network Theory Ltd publishes the Org mode manual as - a book. - - • Bernt Hansen has driven much of the support for auto-repeating - tasks, task state change logging, and the clocktable. His clear - explanations have been critical when we started to adopt the Git - version control system. - - • Manuel Hermenegildo has contributed various ideas, small fixes and - patches. - - • Phil Jackson wrote ‘ol-irc.el’. - - • Scott Jaderholm proposed footnotes, control over whitespace between - folded entries, and column view for properties. - - • Matt Jones wrote MobileOrg Android. - - • Tokuya Kameshima wrote ‘org-wl.el’ and ‘org-mew.el’. - - • Shidai Liu (“Leo”) asked for embedded LaTeX and tested it. He also - provided frequent feedback and some patches. - - • Matt Lundin has proposed last-row references for table formulas and - named invisible anchors. He has also worked a lot on the FAQ. - - • David Maus wrote ‘org-atom.el’, maintains the issues file for Org, - and is a prolific contributor on the mailing list with competent - replies, small fixes and patches. - - • Jason F. McBrayer suggested agenda export to CSV format. - - • Kyle Meyer helped setting up the public-inbox - (https://public-inbox.org/) archive of the Org mailing list - (https://orgmode.org/list/) and has been fixing many bugs. - - • Max Mikhanosha came up with the idea of refiling. - - • Dmitri Minaev sent a patch to set priority limits on a per-file - basis. - - • Stefan Monnier provided a patch to keep the Emacs Lisp compiler - happy. - - • Richard Moreland wrote MobileOrg for the iPhone. - - • Rick Moynihan proposed allowing multiple TODO sequences in a file - and being able to quickly restrict the agenda to a subtree. - - • Todd Neal provided patches for links to Info files and Elisp forms. - - • Greg Newman refreshed the unicorn logo into its current form. - - • Tim O’Callaghan suggested in-file links, search options for general - file links, and tags. - - • Osamu Okano wrote ‘orgcard2ref.pl’, a Perl program to create a text - version of the reference card. - - • Takeshi Okano translated the manual and David O’Toole’s tutorial - into Japanese. - - • Oliver Oppitz suggested multi-state TODO items. - - • Scott Otterson sparked the introduction of descriptive text for - links, among other things. - - • Pete Phillips helped during the development of the TAGS feature, - and provided frequent feedback. - - • Martin Pohlack provided the code snippet to bundle character - insertion into bundles of 20 for undo. - - • Ihor Radchenko helped with fixing bugs and improving the user - experience regarding Org’s speed. - - • T. V. Raman reported bugs and suggested improvements. - - • Matthias Rempe (Oelde) provided ideas, Windows support, and quality - control. - - • Paul Rivier provided the basic implementation of named footnotes. - He also acted as mailing list moderator for some time. - - • Kevin Rogers contributed code to access VM files on remote hosts. - - • Frank Ruell solved the mystery of the ‘keymapp nil’ bug, a conflict - with ‘allout.el’. - - • Jason Riedy generalized the send-receive mechanism for Orgtbl - tables with extensive patches. - - • Philip Rooke created the Org reference card, provided lots of - feedback, developed and applied standards to the Org documentation. - - • Christian Schlauer proposed angular brackets around links, among - other things. - - • Paul Sexton wrote ‘org-ctags.el’. - - • Tom Shannon’s ‘organizer-mode.el’ inspired linking to VM/BBDB/Gnus. - - • Ilya Shlyakhter proposed the Archive Sibling, line numbering in - literal examples, and remote highlighting for referenced code - lines. - - • Stathis Sideris wrote the ‘ditaa.jar’ ASCII to PNG converter that - is now packaged into the org-contrib - (https://git.sr.ht/~bzg/org-contrib) repository. - - • Daniel Sinder came up with the idea of internal archiving by - locking subtrees. - - • Dale Smith proposed link abbreviations. - - • James TD Smith has contributed a large number of patches for useful - tweaks and features. - - • Adam Spiers asked for global linking commands, inspired the link - extension system, added support for Mairix, and proposed the - mapping API. - - • Ulf Stegemann created the table to translate special symbols to - HTML, LaTeX, UTF-8, Latin-1 and ASCII. - - • Andy Stewart contributed code to ‘ol-w3m.el’, to copy HTML content - with links transformation to Org syntax. - - • David O’Toole wrote ‘org-publish.el’ and drafted the manual chapter - about publishing. - - • Jambunathan K. contributed the ODT exporter. - - • Sebastien Vauban reported many issues with LaTeX and Beamer export - and enabled source code highlighting in Gnus. - - • Stefan Vollmar organized a video-recorded talk at the - Max-Planck-Institute for Neurology. He also inspired the creation - of a concept index for HTML export. - - • Jürgen Vollmer contributed code generating the table of contents in - HTML output. - - • Samuel Wales has provided important feedback and bug reports. - - • Chris Wallace provided a patch implementing the ‘QUOTE’ block. - - • David Wainberg suggested archiving, and improvements to the linking - system. - - • Carsten Wimmer suggested some changes and helped fix a bug in - linking to Gnus. - - • Roland Winkler requested additional key bindings to make Org work - on a TTY. - - • Piotr Zielinski wrote ‘org-mouse.el’, proposed agenda blocks and - contributed various ideas and code snippets. - - • Marco Wahl wrote ‘ol-eww.el’. - - -File: org.info, Node: GNU Free Documentation License, Next: Main Index, Prev: History and Acknowledgments, Up: Top - -Appendix C GNU Free Documentation License -***************************************** - - Version 1.3, 3 November 2008 - - Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. - <https://fsf.org/> - - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - 0. PREAMBLE - - The purpose of this License is to make a manual, textbook, or other - functional and useful document “free” in the sense of freedom: to - assure everyone the effective freedom to copy and redistribute it, - with or without modifying it, either commercially or - noncommercially. Secondarily, this License preserves for the - author and publisher a way to get credit for their work, while not - being considered responsible for modifications made by others. - - This License is a kind of “copyleft”, which means that derivative - works of the document must themselves be free in the same sense. - It complements the GNU General Public License, which is a copyleft - license designed for free software. - - We have designed this License in order to use it for manuals for - free software, because free software needs free documentation: a - free program should come with manuals providing the same freedoms - that the software does. But this License is not limited to - software manuals; it can be used for any textual work, regardless - of subject matter or whether it is published as a printed book. We - recommend this License principally for works whose purpose is - instruction or reference. - - 1. APPLICABILITY AND DEFINITIONS - - This License applies to any manual or other work, in any medium, - that contains a notice placed by the copyright holder saying it can - be distributed under the terms of this License. Such a notice - grants a world-wide, royalty-free license, unlimited in duration, - to use that work under the conditions stated herein. The - “Document”, below, refers to any such manual or work. Any member - of the public is a licensee, and is addressed as “you”. You accept - the license if you copy, modify or distribute the work in a way - requiring permission under copyright law. - - A “Modified Version” of the Document means any work containing the - Document or a portion of it, either copied verbatim, or with - modifications and/or translated into another language. - - A “Secondary Section” is a named appendix or a front-matter section - of the Document that deals exclusively with the relationship of the - publishers or authors of the Document to the Document’s overall - subject (or to related matters) and contains nothing that could - fall directly within that overall subject. (Thus, if the Document - is in part a textbook of mathematics, a Secondary Section may not - explain any mathematics.) The relationship could be a matter of - historical connection with the subject or with related matters, or - of legal, commercial, philosophical, ethical or political position - regarding them. - - The “Invariant Sections” are certain Secondary Sections whose - titles are designated, as being those of Invariant Sections, in the - notice that says that the Document is released under this License. - If a section does not fit the above definition of Secondary then it - is not allowed to be designated as Invariant. The Document may - contain zero Invariant Sections. If the Document does not identify - any Invariant Sections then there are none. - - The “Cover Texts” are certain short passages of text that are - listed, as Front-Cover Texts or Back-Cover Texts, in the notice - that says that the Document is released under this License. A - Front-Cover Text may be at most 5 words, and a Back-Cover Text may - be at most 25 words. - - A “Transparent” copy of the Document means a machine-readable copy, - represented in a format whose specification is available to the - general public, that is suitable for revising the document - straightforwardly with generic text editors or (for images composed - of pixels) generic paint programs or (for drawings) some widely - available drawing editor, and that is suitable for input to text - formatters or for automatic translation to a variety of formats - suitable for input to text formatters. A copy made in an otherwise - Transparent file format whose markup, or absence of markup, has - been arranged to thwart or discourage subsequent modification by - readers is not Transparent. An image format is not Transparent if - used for any substantial amount of text. A copy that is not - “Transparent” is called “Opaque”. - - Examples of suitable formats for Transparent copies include plain - ASCII without markup, Texinfo input format, LaTeX input format, - SGML or XML using a publicly available DTD, and standard-conforming - simple HTML, PostScript or PDF designed for human modification. - Examples of transparent image formats include PNG, XCF and JPG. - Opaque formats include proprietary formats that can be read and - edited only by proprietary word processors, SGML or XML for which - the DTD and/or processing tools are not generally available, and - the machine-generated HTML, PostScript or PDF produced by some word - processors for output purposes only. - - The “Title Page” means, for a printed book, the title page itself, - plus such following pages as are needed to hold, legibly, the - material this License requires to appear in the title page. For - works in formats which do not have any title page as such, “Title - Page” means the text near the most prominent appearance of the - work’s title, preceding the beginning of the body of the text. - - The “publisher” means any person or entity that distributes copies - of the Document to the public. - - A section “Entitled XYZ” means a named subunit of the Document - whose title either is precisely XYZ or contains XYZ in parentheses - following text that translates XYZ in another language. (Here XYZ - stands for a specific section name mentioned below, such as - “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) - To “Preserve the Title” of such a section when you modify the - Document means that it remains a section “Entitled XYZ” according - to this definition. - - The Document may include Warranty Disclaimers next to the notice - which states that this License applies to the Document. These - Warranty Disclaimers are considered to be included by reference in - this License, but only as regards disclaiming warranties: any other - implication that these Warranty Disclaimers may have is void and - has no effect on the meaning of this License. - - 2. VERBATIM COPYING - - You may copy and distribute the Document in any medium, either - commercially or noncommercially, provided that this License, the - copyright notices, and the license notice saying this License - applies to the Document are reproduced in all copies, and that you - add no other conditions whatsoever to those of this License. You - may not use technical measures to obstruct or control the reading - or further copying of the copies you make or distribute. However, - you may accept compensation in exchange for copies. If you - distribute a large enough number of copies you must also follow the - conditions in section 3. - - You may also lend copies, under the same conditions stated above, - and you may publicly display copies. - - 3. COPYING IN QUANTITY - - If you publish printed copies (or copies in media that commonly - have printed covers) of the Document, numbering more than 100, and - the Document’s license notice requires Cover Texts, you must - enclose the copies in covers that carry, clearly and legibly, all - these Cover Texts: Front-Cover Texts on the front cover, and - Back-Cover Texts on the back cover. Both covers must also clearly - and legibly identify you as the publisher of these copies. The - front cover must present the full title with all words of the title - equally prominent and visible. You may add other material on the - covers in addition. Copying with changes limited to the covers, as - long as they preserve the title of the Document and satisfy these - conditions, can be treated as verbatim copying in other respects. - - If the required texts for either cover are too voluminous to fit - legibly, you should put the first ones listed (as many as fit - reasonably) on the actual cover, and continue the rest onto - adjacent pages. - - If you publish or distribute Opaque copies of the Document - numbering more than 100, you must either include a machine-readable - Transparent copy along with each Opaque copy, or state in or with - each Opaque copy a computer-network location from which the general - network-using public has access to download using public-standard - network protocols a complete Transparent copy of the Document, free - of added material. If you use the latter option, you must take - reasonably prudent steps, when you begin distribution of Opaque - copies in quantity, to ensure that this Transparent copy will - remain thus accessible at the stated location until at least one - year after the last time you distribute an Opaque copy (directly or - through your agents or retailers) of that edition to the public. - - It is requested, but not required, that you contact the authors of - the Document well before redistributing any large number of copies, - to give them a chance to provide you with an updated version of the - Document. - - 4. MODIFICATIONS - - You may copy and distribute a Modified Version of the Document - under the conditions of sections 2 and 3 above, provided that you - release the Modified Version under precisely this License, with the - Modified Version filling the role of the Document, thus licensing - distribution and modification of the Modified Version to whoever - possesses a copy of it. In addition, you must do these things in - the Modified Version: - - A. Use in the Title Page (and on the covers, if any) a title - distinct from that of the Document, and from those of previous - versions (which should, if there were any, be listed in the - History section of the Document). You may use the same title - as a previous version if the original publisher of that - version gives permission. - - B. List on the Title Page, as authors, one or more persons or - entities responsible for authorship of the modifications in - the Modified Version, together with at least five of the - principal authors of the Document (all of its principal - authors, if it has fewer than five), unless they release you - from this requirement. - - C. State on the Title page the name of the publisher of the - Modified Version, as the publisher. - - D. Preserve all the copyright notices of the Document. - - E. Add an appropriate copyright notice for your modifications - adjacent to the other copyright notices. - - F. Include, immediately after the copyright notices, a license - notice giving the public permission to use the Modified - Version under the terms of this License, in the form shown in - the Addendum below. - - G. Preserve in that license notice the full lists of Invariant - Sections and required Cover Texts given in the Document’s - license notice. - - H. Include an unaltered copy of this License. - - I. Preserve the section Entitled “History”, Preserve its Title, - and add to it an item stating at least the title, year, new - authors, and publisher of the Modified Version as given on the - Title Page. If there is no section Entitled “History” in the - Document, create one stating the title, year, authors, and - publisher of the Document as given on its Title Page, then add - an item describing the Modified Version as stated in the - previous sentence. - - J. Preserve the network location, if any, given in the Document - for public access to a Transparent copy of the Document, and - likewise the network locations given in the Document for - previous versions it was based on. These may be placed in the - “History” section. You may omit a network location for a work - that was published at least four years before the Document - itself, or if the original publisher of the version it refers - to gives permission. - - K. For any section Entitled “Acknowledgements” or “Dedications”, - Preserve the Title of the section, and preserve in the section - all the substance and tone of each of the contributor - acknowledgements and/or dedications given therein. - - L. Preserve all the Invariant Sections of the Document, unaltered - in their text and in their titles. Section numbers or the - equivalent are not considered part of the section titles. - - M. Delete any section Entitled “Endorsements”. Such a section - may not be included in the Modified Version. - - N. Do not retitle any existing section to be Entitled - “Endorsements” or to conflict in title with any Invariant - Section. - - O. Preserve any Warranty Disclaimers. - - If the Modified Version includes new front-matter sections or - appendices that qualify as Secondary Sections and contain no - material copied from the Document, you may at your option designate - some or all of these sections as invariant. To do this, add their - titles to the list of Invariant Sections in the Modified Version’s - license notice. These titles must be distinct from any other - section titles. - - You may add a section Entitled “Endorsements”, provided it contains - nothing but endorsements of your Modified Version by various - parties—for example, statements of peer review or that the text has - been approved by an organization as the authoritative definition of - a standard. - - You may add a passage of up to five words as a Front-Cover Text, - and a passage of up to 25 words as a Back-Cover Text, to the end of - the list of Cover Texts in the Modified Version. Only one passage - of Front-Cover Text and one of Back-Cover Text may be added by (or - through arrangements made by) any one entity. If the Document - already includes a cover text for the same cover, previously added - by you or by arrangement made by the same entity you are acting on - behalf of, you may not add another; but you may replace the old - one, on explicit permission from the previous publisher that added - the old one. - - The author(s) and publisher(s) of the Document do not by this - License give permission to use their names for publicity for or to - assert or imply endorsement of any Modified Version. - - 5. COMBINING DOCUMENTS - - You may combine the Document with other documents released under - this License, under the terms defined in section 4 above for - modified versions, provided that you include in the combination all - of the Invariant Sections of all of the original documents, - unmodified, and list them all as Invariant Sections of your - combined work in its license notice, and that you preserve all - their Warranty Disclaimers. - - The combined work need only contain one copy of this License, and - multiple identical Invariant Sections may be replaced with a single - copy. If there are multiple Invariant Sections with the same name - but different contents, make the title of each such section unique - by adding at the end of it, in parentheses, the name of the - original author or publisher of that section if known, or else a - unique number. Make the same adjustment to the section titles in - the list of Invariant Sections in the license notice of the - combined work. - - In the combination, you must combine any sections Entitled - “History” in the various original documents, forming one section - Entitled “History”; likewise combine any sections Entitled - “Acknowledgements”, and any sections Entitled “Dedications”. You - must delete all sections Entitled “Endorsements.” - - 6. COLLECTIONS OF DOCUMENTS - - You may make a collection consisting of the Document and other - documents released under this License, and replace the individual - copies of this License in the various documents with a single copy - that is included in the collection, provided that you follow the - rules of this License for verbatim copying of each of the documents - in all other respects. - - You may extract a single document from such a collection, and - distribute it individually under this License, provided you insert - a copy of this License into the extracted document, and follow this - License in all other respects regarding verbatim copying of that - document. - - 7. AGGREGATION WITH INDEPENDENT WORKS - - A compilation of the Document or its derivatives with other - separate and independent documents or works, in or on a volume of a - storage or distribution medium, is called an “aggregate” if the - copyright resulting from the compilation is not used to limit the - legal rights of the compilation’s users beyond what the individual - works permit. When the Document is included in an aggregate, this - License does not apply to the other works in the aggregate which - are not themselves derivative works of the Document. - - If the Cover Text requirement of section 3 is applicable to these - copies of the Document, then if the Document is less than one half - of the entire aggregate, the Document’s Cover Texts may be placed - on covers that bracket the Document within the aggregate, or the - electronic equivalent of covers if the Document is in electronic - form. Otherwise they must appear on printed covers that bracket - the whole aggregate. - - 8. TRANSLATION - - Translation is considered a kind of modification, so you may - distribute translations of the Document under the terms of section - 4. Replacing Invariant Sections with translations requires special - permission from their copyright holders, but you may include - translations of some or all Invariant Sections in addition to the - original versions of these Invariant Sections. You may include a - translation of this License, and all the license notices in the - Document, and any Warranty Disclaimers, provided that you also - include the original English version of this License and the - original versions of those notices and disclaimers. In case of a - disagreement between the translation and the original version of - this License or a notice or disclaimer, the original version will - prevail. - - If a section in the Document is Entitled “Acknowledgements”, - “Dedications”, or “History”, the requirement (section 4) to - Preserve its Title (section 1) will typically require changing the - actual title. - - 9. TERMINATION - - You may not copy, modify, sublicense, or distribute the Document - except as expressly provided under this License. Any attempt - otherwise to copy, modify, sublicense, or distribute it is void, - and will automatically terminate your rights under this License. - - However, if you cease all violation of this License, then your - license from a particular copyright holder is reinstated (a) - provisionally, unless and until the copyright holder explicitly and - finally terminates your license, and (b) permanently, if the - copyright holder fails to notify you of the violation by some - reasonable means prior to 60 days after the cessation. - - Moreover, your license from a particular copyright holder is - reinstated permanently if the copyright holder notifies you of the - violation by some reasonable means, this is the first time you have - received notice of violation of this License (for any work) from - that copyright holder, and you cure the violation prior to 30 days - after your receipt of the notice. - - Termination of your rights under this section does not terminate - the licenses of parties who have received copies or rights from you - under this License. If your rights have been terminated and not - permanently reinstated, receipt of a copy of some or all of the - same material does not give you any rights to use it. - - 10. FUTURE REVISIONS OF THIS LICENSE - - The Free Software Foundation may publish new, revised versions of - the GNU Free Documentation License from time to time. Such new - versions will be similar in spirit to the present version, but may - differ in detail to address new problems or concerns. See - <https://www.gnu.org/copyleft/>. - - Each version of the License is given a distinguishing version - number. If the Document specifies that a particular numbered - version of this License “or any later version” applies to it, you - have the option of following the terms and conditions either of - that specified version or of any later version that has been - published (not as a draft) by the Free Software Foundation. If the - Document does not specify a version number of this License, you may - choose any version ever published (not as a draft) by the Free - Software Foundation. If the Document specifies that a proxy can - decide which future versions of this License can be used, that - proxy’s public statement of acceptance of a version permanently - authorizes you to choose that version for the Document. - - 11. RELICENSING - - “Massive Multiauthor Collaboration Site” (or “MMC Site”) means any - World Wide Web server that publishes copyrightable works and also - provides prominent facilities for anybody to edit those works. A - public wiki that anybody can edit is an example of such a server. - A “Massive Multiauthor Collaboration” (or “MMC”) contained in the - site means any set of copyrightable works thus published on the MMC - site. - - “CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 - license published by Creative Commons Corporation, a not-for-profit - corporation with a principal place of business in San Francisco, - California, as well as future copyleft versions of that license - published by that same organization. - - “Incorporate” means to publish or republish a Document, in whole or - in part, as part of another Document. - - An MMC is “eligible for relicensing” if it is licensed under this - License, and if all works that were first published under this - License somewhere other than this MMC, and subsequently - incorporated in whole or in part into the MMC, (1) had no cover - texts or invariant sections, and (2) were thus incorporated prior - to November 1, 2008. - - The operator of an MMC Site may republish an MMC contained in the - site under CC-BY-SA on the same site at any time before August 1, - 2009, provided the MMC is eligible for relicensing. - -C.1 ADDENDUM: How to use this License for your documents -======================================================== - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and license -notices just after the title page: - - Copyright (C) YEAR YOUR NAME. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.3 - or any later version published by the Free Software Foundation; - with no Invariant Sections, no Front-Cover Texts, and no Back-Cover - Texts. A copy of the license is included in the section entitled ``GNU - Free Documentation License''. - - If you have Invariant Sections, Front-Cover Texts and Back-Cover -Texts, replace the “with...Texts.” line with this: - - with the Invariant Sections being LIST THEIR TITLES, with - the Front-Cover Texts being LIST, and with the Back-Cover Texts - being LIST. - - If you have Invariant Sections without Cover Texts, or some other -combination of the three, merge those two alternatives to suit the -situation. - - If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of free -software license, such as the GNU General Public License, to permit -their use in free software. - - -File: org.info, Node: Main Index, Next: Key Index, Prev: GNU Free Documentation License, Up: Top - -D Main Index -************ - - -* Menu: - -* *this*, in post header argument: Results of Evaluation. - (line 253) -* + suffix, in properties: Property Syntax. (line 52) -* _ALL suffix, in properties: Property Syntax. (line 50) -* abbreviation, links: Link Abbreviations. (line 6) -* abstract, in LaTeX export: Special blocks in LaTeX export. - (line 6) -* action, for publishing: Publishing action. (line 6) -* activation: Activation. (line 6) -* active region: Structure Editing. (line 46) -* add-on packages: Add-on Packages. (line 6) -* agenda: Weekly/daily agenda. (line 6) -* agenda dispatcher: Agenda Dispatcher. (line 6) -* agenda files: Agenda Files. (line 6) -* agenda files, removing buffers: Agenda Commands. (line 496) -* agenda filtering: Filtering/limiting agenda items. - (line 20) -* agenda views: Agenda Views. (line 6) -* agenda views, custom: Custom Agenda Views. (line 6) -* agenda views, exporting: Exporting Agenda Views. - (line 6) -* agenda views, exporting <1>: Exporting Agenda Views. - (line 13) -* agenda views, main example: Storing searches. (line 11) -* agenda views, optimization: Speeding Up Your Agendas. - (line 6) -* agenda views, user-defined: Special Agenda Views. - (line 6) -* agenda*, as an agenda views: Storing searches. (line 11) -* agenda, as an agenda views: Storing searches. (line 11) -* agenda, column view: Agenda Column View. (line 6) -* agenda, pipe: Extracting Agenda Information. - (line 6) -* agenda, with block views: Block agenda. (line 6) -* alignment in tables: Column Width and Alignment. - (line 6) -* ALLTAGS, special property: Special Properties. (line 13) -* ALT_TITLE, property: Table of Contents. (line 68) -* ALT_TITLE, property <1>: Headings and sectioning structure. - (line 24) -* angle bracket links: Link Format. (line 6) -* angular brackets, around links: External Links. (line 136) -* anniversaries, from BBDB: Weekly/daily agenda. (line 78) -* API, for mapping: Using the Mapping API. - (line 6) -* API, for properties: Using the Property API. - (line 6) -* APPENDIX, property: Headings and sectioning structure. - (line 20) -* appointment: Timestamps. (line 14) -* appointment <1>: Weekly/daily agenda. (line 125) -* appointment reminders: Weekly/daily agenda. (line 125) -* appt.el: Weekly/daily agenda. (line 125) -* APPT_WARNTIME, keyword: Weekly/daily agenda. (line 125) -* archive locations: Moving subtrees. (line 25) -* ARCHIVE, keyword: Moving subtrees. (line 35) -* ARCHIVE, keyword <1>: In-buffer Settings. (line 15) -* ARCHIVE, property: Property Inheritance. - (line 33) -* ARCHIVE, property <1>: Moving subtrees. (line 37) -* ARCHIVE, tag: Internal archiving. (line 6) -* archived entries, in agenda views: Agenda Views. (line 37) -* archiving: Refiling and Archiving. - (line 6) -* archiving <1>: Archiving. (line 6) -* arguments, in code blocks: Environment of a Code Block. - (line 9) -* ASCII export: ASCII/Latin-1/UTF-8 export. - (line 6) -* ASCII, keyword: ASCII/Latin-1/UTF-8 export. - (line 63) -* Atom feeds: Capture and Attachments. - (line 6) -* Atom feeds <1>: RSS Feeds. (line 6) -* attach from Dired: Attach from Dired. (line 6) -* attachment links: External Links. (line 6) -* attachment links, searching: Search Options. (line 6) -* attachments: Capture and Attachments. - (line 6) -* attachments <1>: Attachments. (line 6) -* ATTR_ASCII, keyword: ASCII/Latin-1/UTF-8 export. - (line 74) -* ATTR_BEAMER, keyword: Beamer specific syntax. - (line 35) -* ATTR_HTML, keyword: Links in HTML export. - (line 27) -* ATTR_HTML, keyword <1>: Tables in HTML export. - (line 11) -* ATTR_HTML, keyword <2>: Images in HTML export. - (line 28) -* ATTR_LATEX, keyword: Images in LaTeX export. - (line 6) -* ATTR_LATEX, keyword <1>: Plain lists in LaTeX export. - (line 6) -* ATTR_LATEX, keyword <2>: Source blocks in LaTeX export. - (line 6) -* ATTR_LATEX, keyword <3>: Example blocks in LaTeX export. - (line 6) -* ATTR_LATEX, keyword <4>: Special blocks in LaTeX export. - (line 6) -* ATTR_LATEX, keyword <5>: Horizontal rules in LaTeX export. - (line 6) -* ATTR_LATEX, keyword <6>: Verse blocks in LaTeX export. - (line 6) -* ATTR_LATEX, keyword <7>: Quote blocks in LaTeX export. - (line 6) -* ATTR_ODT, keyword: Tables in ODT export. - (line 20) -* ATTR_ODT, keyword <1>: Images in ODT export. - (line 31) -* ATTR_ODT, keyword <2>: Images in ODT export. - (line 76) -* ATTR_ODT, keyword <3>: Advanced topics in ODT export. - (line 151) -* ATTR_TEXINFO, keyword: Plain lists in Texinfo export. - (line 6) -* ATTR_TEXINFO, keyword <1>: Tables in Texinfo export. - (line 6) -* ATTR_TEXINFO, keyword <2>: Images in Texinfo export. - (line 6) -* ATTR_TEXINFO, keyword <3>: Quotations in Texinfo export. - (line 6) -* ATTR_TEXINFO, keyword <4>: Special blocks in Texinfo export. - (line 6) -* author: Feedback. (line 6) -* AUTHOR, keyword: Export Settings. (line 25) -* author, macro: Macro Replacement. (line 41) -* auto clocking out after idle time: Resolving idle time. (line 91) -* auto-save, in code block editing: Editing Source Code. (line 11) -* autoload: Activation. (line 6) -* babel, languages: Languages. (line 6) -* babel, library of: Library of Babel. (line 6) -* backslashes, in links: Link Format. (line 17) -* backtrace of an error: Feedback. (line 68) -* BBDB links: External Links. (line 6) -* BBDB, anniversaries: Weekly/daily agenda. (line 78) -* Beamer export: Beamer Export. (line 6) -* BEAMER, keyword: Beamer specific syntax. - (line 19) -* BEAMER_ACT, property: Frames and Blocks in Beamer. - (line 41) -* BEAMER_COL, property: Frames and Blocks in Beamer. - (line 49) -* BEAMER_ENV, property: Frames and Blocks in Beamer. - (line 14) -* BEAMER_FONT_THEME, keyword: Beamer specific export settings. - (line 17) -* BEAMER_HEADER, keyword: Beamer specific export settings. - (line 26) -* BEAMER_INNER_THEME, keyword: Beamer specific export settings. - (line 20) -* BEAMER_OPT, property: Frames and Blocks in Beamer. - (line 41) -* BEAMER_OUTER_THEME, keyword: Beamer specific export settings. - (line 23) -* BEAMER_REF, property: Frames and Blocks in Beamer. - (line 27) -* BEAMER_THEME, keyword: Beamer specific export settings. - (line 11) -* BEGIN clocktable: The clock table. (line 36) -* BEGIN columnview: Capturing column view. - (line 11) -* BEGIN_CENTER: Paragraphs. (line 32) -* BEGIN_COMMENT: Comment Lines. (line 10) -* BEGIN_EXAMPLE: Literal Examples. (line 10) -* BEGIN_EXPORT ascii: ASCII/Latin-1/UTF-8 export. - (line 63) -* BEGIN_EXPORT beamer: Beamer specific syntax. - (line 19) -* BEGIN_EXPORT html: Quoting HTML tags. (line 13) -* BEGIN_EXPORT latex: Quoting LaTeX code. (line 18) -* BEGIN_EXPORT texinfo: Quoting Texinfo code. - (line 9) -* BEGIN_JUSTIFYLEFT: ASCII/Latin-1/UTF-8 export. - (line 84) -* BEGIN_JUSTIFYRIGHT: ASCII/Latin-1/UTF-8 export. - (line 84) -* BEGIN_QUOTE: Paragraphs. (line 25) -* BEGIN_SRC: Literal Examples. (line 38) -* BEGIN_SRC <1>: Structure of Code Blocks. - (line 6) -* BEGIN_VERSE: Paragraphs. (line 13) -* BIND, keyword: Export Settings. (line 210) -* block agenda: Block agenda. (line 6) -* BLOCKED, special property: Special Properties. (line 13) -* blocking, of checkboxes: Checkboxes. (line 45) -* blocks, folding: Blocks. (line 6) -* bold text, markup rules: Emphasis and Monospace. - (line 6) -* boolean logic, for agenda searches: Matching tags and properties. - (line 32) -* bracket links: Link Format. (line 9) -* bug reports: Feedback. (line 6) -* C-c C-c, overview: The Very Busy C-c C-c Key. - (line 6) -* cache results of code evaluation: Evaluating Code Blocks. - (line 106) -* cache, header argument: Evaluating Code Blocks. - (line 106) -* Calc package: The Spreadsheet. (line 6) -* calc.el: Cooperation. (line 7) -* calculations, in tables: Built-in Table Editor. - (line 180) -* calculations, in tables <1>: The Spreadsheet. (line 6) -* calendar commands, from agenda: Agenda Commands. (line 446) -* calendar integration: Weekly/daily agenda. (line 32) -* calendar, for selecting date: The date/time prompt. - (line 78) -* CALL, keyword: Evaluating Code Blocks. - (line 27) -* CAPTION, keyword: Captions. (line 6) -* CAPTION, keyword <1>: Tables in HTML export. - (line 11) -* CAPTION, keyword <2>: Images in HTML export. - (line 28) -* captions, markup rules: Captions. (line 6) -* capture: Capture and Attachments. - (line 6) -* capture <1>: Capture. (line 6) -* capture protocol: The capture protocol. - (line 6) -* capturing, from agenda: Agenda Commands. (line 345) -* category: Categories. (line 6) -* category filtering, in agenda: Filtering/limiting agenda items. - (line 20) -* category, for tags/property match: Matching tags and properties. - (line 65) -* CATEGORY, keyword: Categories. (line 6) -* CATEGORY, keyword <1>: In-buffer Settings. (line 19) -* CATEGORY, property: Property Inheritance. - (line 29) -* CATEGORY, property <1>: Categories. (line 12) -* CDLaTeX: CDLaTeX mode. (line 6) -* cdlatex.el: Cooperation. (line 24) -* center blocks: Paragraphs. (line 32) -* center image in LaTeX export: Images in LaTeX export. - (line 60) -* change agenda display: Agenda Commands. (line 63) -* checkbox blocking: Checkboxes. (line 45) -* checkbox statistics: Checkboxes. (line 29) -* checkboxes: Checkboxes. (line 6) -* checkboxes and TODO dependencies: TODO dependencies. (line 53) -* children, subtree visibility state: Global and local cycling. - (line 6) -* CINDEX, keyword: Indices. (line 6) -* citation: Citation handling. (line 6) -* CLASS, property: iCalendar Export. (line 51) -* clean outline view: Clean View. (line 6) -* clocking time: Clocking Work Time. (line 6) -* CLOCKSUM, special property: Special Properties. (line 13) -* CLOCKSUM, special property <1>: Agenda Column View. (line 32) -* CLOCKSUM_T, special property: Special Properties. (line 13) -* CLOCKSUM_T, special property <1>: Agenda Column View. (line 56) -* clocktable, dynamic block: The clock table. (line 6) -* CLOCK_MODELINE_TOTAL, property: Clocking commands. (line 21) -* CLOSED, special property: Special Properties. (line 13) -* code block, batch execution: Batch Execution. (line 6) -* code block, editing: Editing Source Code. (line 6) -* code block, evaluating: Evaluating Code Blocks. - (line 6) -* code block, exporting: Exporting Code Blocks. - (line 6) -* code block, extracting source code: Extracting Source Code. - (line 6) -* code block, key bindings: Key bindings and Useful Functions. - (line 6) -* code block, languages: Languages. (line 6) -* code block, library: Library of Babel. (line 6) -* code block, noweb reference: Noweb Reference Syntax. - (line 6) -* code block, results of evaluation: Results of Evaluation. - (line 6) -* code block, structure: Structure of Code Blocks. - (line 6) -* code line references, markup rules: Literal Examples. (line 6) -* code text, markup rules: Emphasis and Monospace. - (line 6) -* colnames, header argument: Environment of a Code Block. - (line 52) -* column formula: Column formulas. (line 6) -* column view, for properties: Defining columns. (line 6) -* column view, in agenda: Agenda Column View. (line 6) -* column, of field coordinates: References. (line 90) -* COLUMNS, keyword: Scope of column definitions. - (line 18) -* COLUMNS, property: Property Inheritance. - (line 22) -* COLUMNS, property <1>: In-buffer Settings. (line 23) -* comma escape, in literal examples: Literal Examples. (line 14) -* commands, in agenda buffer: Agenda Commands. (line 6) -* comment block: Comment Lines. (line 10) -* comment lines: Comment Lines. (line 6) -* comment trees: Comment Lines. (line 13) -* commented entries, in agenda views: Agenda Views. (line 37) -* comments, header argument: Extracting Source Code. - (line 46) -* completion, of dictionary words: Completion. (line 6) -* completion, of file names: Handling Links. (line 94) -* completion, of link abbreviations: Completion. (line 6) -* completion, of links: Handling Links. (line 71) -* completion, of option keywords: Per-file keywords. (line 26) -* completion, of option keywords <1>: Completion. (line 6) -* completion, of property keys: Completion. (line 6) -* completion, of tags: Setting Tags. (line 11) -* completion, of tags <1>: Completion. (line 6) -* completion, of TeX symbols: Completion. (line 6) -* completion, of TODO keywords: Workflow states. (line 17) -* completion, of TODO keywords <1>: Completion. (line 6) -* concept index, in Texinfo export: Indices. (line 6) -* constants, in calculations: References. (line 114) -* CONSTANTS, keyword: References. (line 114) -* CONSTANTS, keyword <1>: In-buffer Settings. (line 28) -* constants.el: Cooperation. (line 14) -* contents, global visibility state: Global and local cycling. - (line 20) -* continuous clocking: Resolving idle time. (line 78) -* control code block evaluation: Evaluating Code Blocks. - (line 81) -* convert: Advanced topics in ODT export. - (line 12) -* converter: Advanced topics in ODT export. - (line 12) -* COOKIE_DATA, property: Breaking Down Tasks. (line 21) -* COOKIE_DATA, property <1>: Checkboxes. (line 29) -* coordinates, of field: References. (line 90) -* copying notes: Refiling and Archiving. - (line 6) -* copying notes <1>: Refile and Copy. (line 6) -* copying, of subtrees: Structure Editing. (line 6) -* COPYING, property: Texinfo title and copyright page. - (line 19) -* countdown timer: Timers. (line 6) -* counter, macro: Macro Replacement. (line 75) -* CREATOR, keyword: Export Settings. (line 28) -* CSS, for HTML export: CSS support. (line 6) -* cua.el: Conflicts. (line 17) -* custom agenda views: Custom Agenda Views. (line 6) -* custom date/time format: Custom time format. (line 6) -* custom search strings: Custom Searches. (line 6) -* CUSTOM_ID, property: Internal Links. (line 11) -* CUSTOM_ID, property <1>: Handling Links. (line 21) -* cutting, of subtrees: Structure Editing. (line 6) -* cycling, in plain lists: Plain Lists. (line 70) -* cycling, of agenda files: Agenda Files. (line 26) -* cycling, of TODO states: TODO Basics. (line 14) -* cycling, visibility: Visibility Cycling. (line 6) -* daily agenda: Weekly/daily agenda. (line 6) -* dash, special symbol: Special Symbols. (line 36) -* data type index, in Texinfo export: Indices. (line 6) -* date format, custom: Custom time format. (line 6) -* date range: Timestamps. (line 42) -* date stamp: Dates and Times. (line 6) -* date stamps: Timestamps. (line 6) -* date tree: Using capture. (line 7) -* DATE, keyword: Export Settings. (line 32) -* date, macro: Macro Replacement. (line 49) -* date, reading in minibuffer: The date/time prompt. - (line 6) -* dates: Dates and Times. (line 6) -* DEADLINE marker: Deadlines and Scheduling. - (line 11) -* DEADLINE, special property: Special Properties. (line 13) -* deadlines: Timestamps. (line 6) -* debugging, of table formulas: Editing and debugging formulas. - (line 132) -* default header arguments per language: Using Header Arguments. - (line 36) -* defining new protocols: Protocols. (line 25) -* demotion, of subtrees: Structure Editing. (line 6) -* dependencies, of TODO states: TODO dependencies. (line 6) -* DESCRIPTION, keyword: Beamer specific export settings. - (line 30) -* DESCRIPTION, keyword <1>: HTML specific export settings. - (line 10) -* DESCRIPTION, keyword <2>: LaTeX specific export settings. - (line 11) -* DESCRIPTION, keyword <3>: ODT specific export settings. - (line 11) -* DESCRIPTION, property: Headings and sectioning structure. - (line 24) -* DESCRIPTION, property <1>: iCalendar Export. (line 51) -* diary entries, creating from agenda: Agenda Commands. (line 455) -* diary integration: Weekly/daily agenda. (line 32) -* diary style timestamps: Timestamps. (line 34) -* dictionary word completion: Completion. (line 6) -* dir file, in Texinfo export: Info directory file. (line 6) -* dir, header argument: Environment of a Code Block. - (line 309) -* DIR, property: Attachment defaults and dispatcher. - (line 68) -* DIR, property <1>: Attachment defaults and dispatcher. - (line 73) -* directories, for publishing: Sources and destinations. - (line 6) -* dispatcher, for export commands: The Export Dispatcher. - (line 6) -* dispatching agenda commands: Agenda Dispatcher. (line 6) -* display changing, in agenda: Agenda Commands. (line 63) -* doc, docx, rtf: Advanced topics in ODT export. - (line 12) -* document structure: Document Structure. (line 6) -* document title: Export Settings. (line 60) -* documentation: Documentation Access. - (line 6) -* DONE, final TODO keyword: Per-file keywords. (line 29) -* drawer, for properties: Property Syntax. (line 6) -* drawer, for state change recording: Tracking TODO state changes. - (line 6) -* drawers: Drawers. (line 6) -* duration, computing: Durations and time values. - (line 6) -* dvipng: Math formatting in HTML export. - (line 6) -* dvipng <1>: LaTeX math snippets. (line 50) -* dvisvgm: Math formatting in HTML export. - (line 6) -* dvisvgm <1>: LaTeX math snippets. (line 50) -* dynamic blocks: Dynamic Blocks. (line 6) -* dynamic indentation: Clean View. (line 6) -* ecomplete.el: Conflicts. (line 32) -* editing tables: Tables. (line 6) -* editing, of table formulas: Editing and debugging formulas. - (line 6) -* edits, catching invisible: Catching invisible edits. - (line 6) -* effort estimates: Effort Estimates. (line 6) -* effort filtering, in agenda: Filtering/limiting agenda items. - (line 20) -* EFFORT, property: Effort Estimates. (line 6) -* Elisp links: External Links. (line 6) -* ellipsis, special symbol: Special Symbols. (line 36) -* ELPA: Activation. (line 6) -* EMAIL, keyword: Export Settings. (line 35) -* email, macro: Macro Replacement. (line 41) -* embedding images in ODT: Images in ODT export. - (line 6) -* entities: Special Symbols. (line 6) -* enum, Texinfo attribute: Plain lists in Texinfo export. - (line 35) -* epilogue, header argument: Environment of a Code Block. - (line 359) -* escape character: Escape Character. (line 6) -* escape syntax, for links: Link Format. (line 17) -* eval, header argument: Evaluating Code Blocks. - (line 81) -* evaluate time range: Creating Timestamps. (line 62) -* example block: Literal Examples. (line 10) -* example blocks, in LaTeX export: Example blocks in LaTeX export. - (line 6) -* EXCLUDE_TAGS, keyword: Export Settings. (line 52) -* excluding entries from table of contents: Table of Contents. - (line 15) -* export back-end: Exporting. (line 12) -* export, dispatcher: The Export Dispatcher. - (line 6) -* export, include files: Include Files. (line 6) -* export, OpenDocument: OpenDocument Text Export. - (line 6) -* Export, settings: Export Settings. (line 6) -* Export, writing back-ends: Adding Export Back-ends. - (line 6) -* exporting: Exporting. (line 6) -* exporting agenda views: Exporting Agenda Views. - (line 13) -* exporting, not: Comment Lines. (line 6) -* exports, header argument: Exporting Code Blocks. - (line 14) -* EXPORT_FILE_NAME, keyword: Export Settings. (line 64) -* EXPORT_FILE_NAME, property: ODT export commands. (line 9) -* EXPORT_LATEX_CLASS, property: LaTeX header and sectioning. - (line 23) -* EXPORT_LATEX_CLASS_OPTIONS, property: LaTeX header and sectioning. - (line 23) -* extended TODO keywords: TODO Extensions. (line 6) -* external archiving: Moving subtrees. (line 6) -* external links: External Links. (line 6) -* external links, in HTML export: Links in HTML export. - (line 6) -* faces, for TODO keywords: Faces for TODO keywords. - (line 6) -* FAQ: Summary. (line 49) -* feedback: Feedback. (line 6) -* field coordinates: References. (line 90) -* field formula: Field and range formulas. - (line 6) -* field references: References. (line 15) -* file links: External Links. (line 6) -* file links, searching: Search Options. (line 6) -* file name completion: Handling Links. (line 94) -* file, header argument: Results of Evaluation. - (line 119) -* FILE, special property: Special Properties. (line 13) -* file-desc, header argument: Results of Evaluation. - (line 140) -* file-ext, header argument: Results of Evaluation. - (line 129) -* file-mode, header argument: Results of Evaluation. - (line 151) -* files for agenda: Agenda Files. (line 6) -* files, adding to agenda list: Agenda Files. (line 16) -* files, selecting for publishing: Selecting files. (line 6) -* FILETAGS, keyword: Tag Inheritance. (line 20) -* FILETAGS, keyword <1>: In-buffer Settings. (line 34) -* filladapt.el: Conflicts. (line 43) -* filtering entries, in agenda: Filtering/limiting agenda items. - (line 20) -* Filters, exporting: Advanced Export Configuration. - (line 31) -* FINDEX, keyword: Indices. (line 6) -* FLAGGED, tag: Pulling from the mobile application. - (line 18) -* folded, subtree visibility state: Global and local cycling. - (line 6) -* folding, sparse trees: Sparse Trees. (line 6) -* following links: Handling Links. (line 104) -* footers, in code blocks: Environment of a Code Block. - (line 351) -* footnotes: Creating Footnotes. (line 6) -* format specifier, in spreadsheet: Formula syntax for Calc. - (line 17) -* format, of links: Link Format. (line 6) -* formatting source code, markup rules: Literal Examples. (line 31) -* formula debugging: Editing and debugging formulas. - (line 132) -* formula editing: Editing and debugging formulas. - (line 6) -* formula syntax, Calc: Formula syntax for Calc. - (line 6) -* formula, for individual table field: Field and range formulas. - (line 6) -* formula, for range of fields: Field and range formulas. - (line 6) -* formula, for table column: Column formulas. (line 6) -* formula, in tables: Built-in Table Editor. - (line 180) -* function index, in Texinfo export: Indices. (line 6) -* global cycling: Global and local cycling. - (line 20) -* global key bindings: Activation. (line 6) -* global TODO list: Global TODO list. (line 6) -* global visibility states: Global and local cycling. - (line 20) -* Gnus links: External Links. (line 6) -* graph, in tables: Org Plot. (line 6) -* group tags: Tag Hierarchy. (line 6) -* group tags, as regular expressions: Matching tags and properties. - (line 58) -* grouping columns in tables: Column Groups. (line 6) -* habits: Tracking your habits. - (line 6) -* hacking: Hacking. (line 6) -* header arguments per language: Using Header Arguments. - (line 74) -* header arguments, in code blocks: Structure of Code Blocks. - (line 57) -* header lines, in tables: Built-in Table Editor. - (line 6) -* header, for LaTeX files: LaTeX header and sectioning. - (line 6) -* HEADER, keyword: Using Header Arguments. - (line 114) -* headers, in code blocks: Environment of a Code Block. - (line 351) -* headline navigation: Motion. (line 6) -* headline tagging: Tags. (line 6) -* headline, promotion and demotion: Structure Editing. (line 6) -* headlines: Headlines. (line 6) -* headlines, in HTML export: Headlines in HTML export. - (line 6) -* Help links: External Links. (line 6) -* hide text: Visibility Cycling. (line 6) -* hiding leading stars: Clean View. (line 6) -* hlines, header argument: Results of Evaluation. - (line 69) -* hooks: Hooks. (line 6) -* horizontal rule, in tables: Built-in Table Editor. - (line 6) -* horizontal rules, in ASCII export: ASCII/Latin-1/UTF-8 export. - (line 74) -* horizontal rules, in LaTeX export: Horizontal rules in LaTeX export. - (line 6) -* horizontal rules, markup rules: Horizontal Rules. (line 6) -* HTML export: HTML Export. (line 6) -* HTML export, CSS: CSS support. (line 6) -* HTML, and Orgtbl mode: Translator functions. - (line 6) -* HTML, keyword: Quoting HTML tags. (line 13) -* html-style, OPTIONS item: CSS support. (line 56) -* HTML5, export new elements: HTML doctypes. (line 25) -* HTML_CONTAINER, keyword: HTML specific export settings. - (line 22) -* HTML_CONTAINER_CLASS, property: CSS support. (line 62) -* HTML_DOCTYPE, keyword: HTML specific export settings. - (line 19) -* HTML_HEAD, keyword: HTML specific export settings. - (line 38) -* HTML_HEAD, keyword <1>: CSS support. (line 49) -* HTML_HEADLINE_CLASS, property: CSS support. (line 62) -* HTML_HEAD_EXTRA, keyword: HTML specific export settings. - (line 42) -* HTML_HEAD_EXTRA, keyword <1>: CSS support. (line 49) -* HTML_INCLUDE_STYLE, keyword: CSS support. (line 44) -* HTML_LINK_HOME, keyword: HTML specific export settings. - (line 26) -* HTML_LINK_UP, keyword: HTML specific export settings. - (line 29) -* HTML_MATHJAX, keyword: HTML specific export settings. - (line 33) -* hyperlinks: Hyperlinks. (line 6) -* hyperlinks, adding new types: Adding Hyperlink Types. - (line 6) -* iCalendar export: iCalendar Export. (line 6) -* ID, property: Handling Links. (line 21) -* ID, property <1>: Capturing column view. - (line 34) -* ID, property <2>: iCalendar Export. (line 26) -* identify, ImageMagick: Images in ODT export. - (line 34) -* idle, resolve, dangling: Resolving idle time. (line 9) -* image, centering in LaTeX export: Images in LaTeX export. - (line 60) -* ImageMagick: Math formatting in HTML export. - (line 6) -* ImageMagick <1>: LaTeX math snippets. (line 50) -* images, embedding in ODT: Images in ODT export. - (line 6) -* images, inline in HTML: Images in HTML export. - (line 6) -* images, inline in LaTeX: Images in LaTeX export. - (line 6) -* images, markup rules: Images. (line 6) -* imenu.el: Cooperation. (line 29) -* in-buffer settings: In-buffer Settings. (line 6) -* inactive timestamp: Timestamps. (line 50) -* include files, during export: Include Files. (line 6) -* INCLUDE, keyword: Include Files. (line 6) -* Indent mode: Org Indent Mode. (line 6) -* indentation, in code blocks: Editing Source Code. (line 32) -* indentation, in source blocks: Literal Examples. (line 81) -* index, in a publishing project: Generating an index. (line 6) -* INDEX, keyword: Generating an index. (line 17) -* INDEX, property: Indices. (line 14) -* indic, Texinfo attribute: Plain lists in Texinfo export. - (line 12) -* Info: Documentation Access. - (line 6) -* Info directory file, in Texinfo export: Info directory file. - (line 6) -* Info links: External Links. (line 6) -* INFOJS_OPT, keyword: JavaScript support. (line 19) -* inheritance, of properties: Property Inheritance. - (line 6) -* inheritance, of tags: Tag Inheritance. (line 6) -* inline, in LaTeX export: Quoting LaTeX code. (line 10) -* inlining images: Images. (line 6) -* inlining images in HTML: Images in HTML export. - (line 6) -* inlining images in LaTeX: Images in LaTeX export. - (line 6) -* input-file, macro: Macro Replacement. (line 64) -* inserting links: Handling Links. (line 71) -* insertion, of templates: Structure Templates. (line 6) -* insertion, of templates <1>: Structure Templates. (line 21) -* install-info, in Texinfo export: Info directory file. (line 6) -* installation: Installation. (line 6) -* Installing Org protocol: Protocols. (line 14) -* internal links: Internal Links. (line 6) -* internal links, in HTML export: Links in HTML export. - (line 6) -* introduction: Introduction. (line 6) -* IRC links: External Links. (line 6) -* italic text, markup rules: Emphasis and Monospace. - (line 6) -* ITEM, special property: Special Properties. (line 13) -* jumping, to headlines: Motion. (line 6) -* key bindings, global: Activation. (line 6) -* keystroke index, in Texinfo export: Indices. (line 6) -* keyword options: Per-file keywords. (line 6) -* keyword, macro: Macro Replacement. (line 41) -* KEYWORDS, keyword: Beamer specific export settings. - (line 37) -* KEYWORDS, keyword <1>: HTML specific export settings. - (line 46) -* KEYWORDS, keyword <2>: LaTeX specific export settings. - (line 54) -* KEYWORDS, keyword <3>: ODT specific export settings. - (line 16) -* KINDEX, keyword: Indices. (line 6) -* language specific default header arguments: Using Header Arguments. - (line 36) -* language specific header arguments properties: Using Header Arguments. - (line 74) -* language, in code blocks: Structure of Code Blocks. - (line 47) -* LANGUAGE, keyword: Export Settings. (line 38) -* LANGUAGE, keyword <1>: LaTeX specific export settings. - (line 20) -* LAST_REPEAT, property: Clocking commands. (line 21) -* LaTeX class: LaTeX header and sectioning. - (line 6) -* LaTeX export: LaTeX Export. (line 6) -* LaTeX fragments: LaTeX fragments. (line 6) -* LaTeX fragments, preview: Previewing LaTeX fragments. - (line 6) -* LaTeX header: LaTeX header and sectioning. - (line 6) -* LaTeX interpretation: Embedded LaTeX. (line 6) -* LaTeX sectioning structure: LaTeX header and sectioning. - (line 6) -* LaTeX, and Orgtbl mode: A LaTeX example. (line 6) -* LATEX, keyword: Quoting LaTeX code. (line 14) -* LATEX_CLASS, keyword: LaTeX specific export settings. - (line 32) -* LATEX_CLASS, keyword <1>: LaTeX header and sectioning. - (line 23) -* LATEX_CLASS_OPTIONS, keyword: LaTeX specific export settings. - (line 40) -* LATEX_CLASS_OPTIONS, keyword <1>: LaTeX header and sectioning. - (line 23) -* LATEX_COMPILER, keyword: LaTeX/PDF export commands. - (line 25) -* LATEX_COMPILER, keyword <1>: LaTeX specific export settings. - (line 44) -* LATEX_HEADER, keyword: HTML specific export settings. - (line 51) -* LATEX_HEADER, keyword <1>: LaTeX specific export settings. - (line 49) -* LATEX_HEADER, keyword <2>: LaTeX header and sectioning. - (line 30) -* LATEX_HEADER_EXTRA, keyword: LaTeX specific export settings. - (line 49) -* LATEX_HEADER_EXTRA, keyword <1>: LaTeX header and sectioning. - (line 30) -* Latin-1 export: ASCII/Latin-1/UTF-8 export. - (line 6) -* lettered lists, in Texinfo export: Plain lists in Texinfo export. - (line 35) -* level, for tags/property match: Matching tags and properties. - (line 65) -* LibreOffice: OpenDocument Text Export. - (line 6) -* limits, in agenda: Filtering/limiting agenda items. - (line 129) -* line breaks, markup rules: Paragraphs. (line 9) -* lines, include: Include Files. (line 36) -* link abbreviations: Link Abbreviations. (line 6) -* link abbreviations, completion of: Completion. (line 6) -* link completion: Handling Links. (line 71) -* link format: Link Format. (line 6) -* LINK, keyword: Link Abbreviations. (line 49) -* LINK, keyword <1>: In-buffer Settings. (line 38) -* links, external: External Links. (line 6) -* links, finding next/previous: Handling Links. (line 153) -* links, handling: Handling Links. (line 6) -* links, in HTML export: Links in HTML export. - (line 6) -* links, in ODT export: Links in ODT export. (line 6) -* links, internal: Internal Links. (line 6) -* links, publishing: Publishing links. (line 6) -* links, radio targets: Radio Targets. (line 6) -* links, returning to: Handling Links. (line 146) -* linter: Org Syntax. (line 24) -* Lisp forms, as table formulas: Formula syntax for Lisp. - (line 6) -* list of listings: Table of Contents. (line 6) -* list of tables: Table of Contents. (line 6) -* lists, in other modes: Tables in Arbitrary Syntax. - (line 6) -* lists, ordered: Plain Lists. (line 6) -* lists, plain: Plain Lists. (line 6) -* literal examples, markup rules: Literal Examples. (line 6) -* LOCATION, property: iCalendar Export. (line 51) -* logging, of progress: Progress Logging. (line 6) -* LOGGING, property: Tracking TODO state changes. - (line 45) -* LOGGING, property <1>: Property Inheritance. - (line 37) -* LOG_INTO_DRAWER, property: Tracking TODO state changes. - (line 6) -* LOG_INTO_DRAWER, property <1>: Clocking commands. (line 7) -* lookup functions in tables: Lookup functions. (line 6) -* lualatex: LaTeX/PDF export commands. - (line 25) -* macro replacement, during export: Macro Replacement. (line 6) -* MACRO, keyword: Macro Replacement. (line 6) -* maintainer: Feedback. (line 6) -* mapping entries, API: Using the Mapping API. - (line 6) -* mappings in open-source protocol: The open-source protocol. - (line 67) -* mark ring: Handling Links. (line 141) -* Markdown export: Markdown Export. (line 6) -* marking characters, tables: Advanced features. (line 39) -* match view: Matching tags and properties. - (line 6) -* matching, of properties: Matching tags and properties. - (line 6) -* matching, of tags: Matching tags and properties. - (line 6) -* matching, tags: Tags. (line 6) -* math symbols: Special Symbols. (line 6) -* MathJax: Math formatting in HTML export. - (line 6) -* MathML: LaTeX math snippets. (line 10) -* MH-E links: External Links. (line 6) -* minlevel, include: Include Files. (line 22) -* minor mode for tables: Orgtbl Mode. (line 6) -* mkdirp, header argument: Environment of a Code Block. - (line 309) -* mkdirp, header argument <1>: Extracting Source Code. - (line 42) -* mode, for Calc: Formula syntax for Calc. - (line 17) -* modification-time, macro: Macro Replacement. (line 56) -* motion commands in agenda: Agenda Commands. (line 19) -* motion, between headlines: Motion. (line 6) -* multiple formula lines: Editing and debugging formulas. - (line 98) -* multiple items in Texinfo lists: Plain lists in Texinfo export. - (line 17) -* n, macro: Macro Replacement. (line 75) -* NAME keyword, in source blocks: Structure of Code Blocks. - (line 6) -* NAME, keyword: References. (line 135) -* NAME, keyword <1>: Internal Links. (line 21) -* name, of column or field: References. (line 114) -* name, of column or field <1>: References. (line 135) -* named references: References. (line 114) -* names as TODO keywords: TODO types. (line 6) -* narrow columns in tables: Column Width and Alignment. - (line 6) -* no-expand, header argument: Extracting Source Code. - (line 97) -* NOBLOCKING, property: TODO dependencies. (line 29) -* noweb, header argument: Noweb Reference Syntax. - (line 18) -* noweb-ref, header argument: Noweb Reference Syntax. - (line 6) -* noweb-sep, header argument: Noweb Reference Syntax. - (line 96) -* number headlines: Dynamic Headline Numbering. - (line 6) -* occur, command: Sparse Trees. (line 6) -* occur-tree: Storing searches. (line 11) -* odd-levels-only outlines: Clean View. (line 6) -* ODT: OpenDocument Text Export. - (line 6) -* ODT, keyword: Advanced topics in ODT export. - (line 120) -* ODT_STYLES_FILE, keyword: ODT specific export settings. - (line 22) -* ODT_STYLES_FILE, keyword <1>: Applying custom styles. - (line 29) -* only-contents, include: Include Files. (line 53) -* open-source protocol: The open-source protocol. - (line 6) -* OpenDocument: OpenDocument Text Export. - (line 6) -* option keyword completion: Completion. (line 6) -* options, for custom agenda views: Setting options. (line 6) -* options, for export: Export Settings. (line 6) -* options, for publishing: Publishing options. (line 6) -* OPTIONS, keyword: Export Settings. (line 6) -* ordered lists: Plain Lists. (line 6) -* ORDERED, property: TODO dependencies. (line 6) -* ORDERED, property <1>: Checkboxes. (line 45) -* Org export: Org Export. (line 6) -* Org mode, turning on: Activation. (line 24) -* Org Num mode: Dynamic Headline Numbering. - (line 6) -* Org protocol, set-up: Protocols. (line 14) -* org-agenda, command: Weekly/daily agenda. (line 10) -* org-latex-default-quote-environment: Quote blocks in LaTeX export. - (line 6) -* Orgtbl mode: Orgtbl Mode. (line 6) -* Orgtbl mode <1>: Tables in Arbitrary Syntax. - (line 6) -* ORGTBL, keyword: Radio tables. (line 21) -* outline tree: Headlines. (line 6) -* output-dir, header argument: Results of Evaluation. - (line 119) -* overview, global visibility state: Global and local cycling. - (line 20) -* packages, interaction with other: Interaction. (line 6) -* padline, header argument: Extracting Source Code. - (line 73) -* paragraphs, markup rules: Paragraphs. (line 6) -* passing arguments to code blocks: Environment of a Code Block. - (line 9) -* pasting, of subtrees: Structure Editing. (line 6) -* PDF export: LaTeX Export. (line 6) -* pdflatex: LaTeX/PDF export commands. - (line 25) -* per-file keywords: Per-file keywords. (line 6) -* PINDEX, keyword: Indices. (line 6) -* plain links: Link Format. (line 6) -* plain lists: Plain Lists. (line 6) -* plain lists, in LaTeX export: Plain lists in LaTeX export. - (line 6) -* plain text external links: External Links. (line 136) -* plot tables using Gnuplot: Org Plot. (line 6) -* PLOT, keyword: Org Plot. (line 12) -* post, header argument: Results of Evaluation. - (line 253) -* presentation, of agenda items: Presentation and Sorting. - (line 6) -* print edition: Summary. (line 54) -* printing sparse trees: Sparse Trees. (line 52) -* priorities: Priorities. (line 6) -* PRIORITIES, keyword: Priorities. (line 52) -* PRIORITIES, keyword <1>: In-buffer Settings. (line 43) -* priorities, of agenda items: Sorting of agenda items. - (line 6) -* priority cookie: Priorities. (line 6) -* PRIORITY, special property: Special Properties. (line 13) -* program index, in Texinfo export: Indices. (line 6) -* progress logging: Progress Logging. (line 6) -* projects, for publishing: Project alist. (line 6) -* prologue, header argument: Environment of a Code Block. - (line 351) -* promotion, of subtrees: Structure Editing. (line 6) -* proof, in LaTeX export: Special blocks in LaTeX export. - (line 6) -* properties: Properties and Columns. - (line 6) -* properties, API: Using the Property API. - (line 6) -* properties, column view: Defining columns. (line 6) -* properties, inheritance: Property Inheritance. - (line 6) -* properties, searching: Property Searches. (line 6) -* properties, special: Special Properties. (line 6) -* property syntax: Property Syntax. (line 6) -* PROPERTY, keyword: Property Syntax. (line 50) -* PROPERTY, keyword <1>: In-buffer Settings. (line 48) -* property, macro: Macro Replacement. (line 68) -* protocol, capture: The capture protocol. - (line 6) -* protocol, new protocol: Protocols. (line 25) -* protocol, open-source: The open-source protocol. - (line 6) -* protocol, open-source rewritten URL: The open-source protocol. - (line 32) -* protocol, open-source, set-up mapping: The open-source protocol. - (line 67) -* protocol, store-link: The store-link protocol. - (line 6) -* protocols, for external access: Capture and Attachments. - (line 6) -* protocols, for external access <1>: Protocols. (line 6) -* publishing: Publishing. (line 6) -* publishing options: Publishing options. (line 6) -* query editing, in agenda: Filtering/limiting agenda items. - (line 20) -* quote blocks: Paragraphs. (line 25) -* quote blocks, in LaTeX export: Quote blocks in LaTeX export. - (line 6) -* radio button, checkbox as: Checkboxes. (line 75) -* radio tables: Radio tables. (line 6) -* radio targets: Radio Targets. (line 6) -* range formula: Field and range formulas. - (line 6) -* range references: References. (line 64) -* ranges, time: Timestamps. (line 6) -* recomputing table fields: Updating the table. (line 6) -* references: References. (line 6) -* references, named: References. (line 114) -* references, remote: References. (line 135) -* references, to a different table: References. (line 135) -* references, to fields: References. (line 15) -* references, to ranges: References. (line 64) -* refiling notes: Refiling and Archiving. - (line 6) -* refiling notes <1>: Refile and Copy. (line 6) -* refresh set-up: In-buffer Settings. (line 11) -* region, active: Structure Editing. (line 46) -* regular expressions syntax: Regular Expressions. (line 6) -* regular expressions, in searches: Regular Expressions. (line 6) -* regular expressions, with tags search: Matching tags and properties. - (line 53) -* relative timer: Timers. (line 6) -* reminders: Weekly/daily agenda. (line 125) -* remote editing, bulk, from agenda: Agenda Commands. (line 352) -* remote editing, from agenda: Agenda Commands. (line 223) -* remote editing, undo: Agenda Commands. (line 227) -* remote references: References. (line 135) -* repeated tasks: Repeated tasks. (line 6) -* report, of clocked time: The clock table. (line 6) -* reporting a bug: Feedback. (line 6) -* resolve idle time: Resolving idle time. (line 9) -* results, header argument: Results of Evaluation. - (line 6) -* RESULTS, keyword: Evaluating Code Blocks. - (line 6) -* results, macro: Macro Replacement. (line 84) -* revealing context: Global and local cycling. - (line 43) -* rewritten URL in open-source protocol: The open-source protocol. - (line 32) -* Rmail links: External Links. (line 6) -* row separator, in tables: Built-in Table Editor. - (line 6) -* row, of field coordinates: References. (line 90) -* rownames, header argument: Environment of a Code Block. - (line 77) -* RSS feeds: Capture and Attachments. - (line 6) -* RSS feeds <1>: RSS Feeds. (line 6) -* rsync: Uploading Files. (line 6) -* SCHEDULED marker: Deadlines and Scheduling. - (line 31) -* SCHEDULED, special property: Special Properties. (line 13) -* scheduling: Timestamps. (line 6) -* scripts, for agenda processing: Extracting Agenda Information. - (line 6) -* search option in file links: Search Options. (line 6) -* search strings, custom: Custom Searches. (line 6) -* search view: Search view. (line 6) -* searching for tags: Tag Searches. (line 6) -* searching, for text: Search view. (line 6) -* searching, of properties: Property Searches. (line 6) -* sectioning structure, for LaTeX export: LaTeX header and sectioning. - (line 6) -* SELECT_TAGS, keyword: Export Settings. (line 44) -* sep, header argument: Results of Evaluation. - (line 147) -* sep, Texinfo attribute: Plain lists in Texinfo export. - (line 17) -* SEQ_TODO, keyword: Per-file keywords. (line 6) -* SEQ_TODO, keyword <1>: In-buffer Settings. (line 190) -* session, header argument: Environment of a Code Block. - (line 279) -* setting tags: Setting Tags. (line 6) -* SETUPFILE, keyword: Export Settings. (line 13) -* SETUPFILE, keyword <1>: In-buffer Settings. (line 53) -* sexp timestamps: Timestamps. (line 34) -* shebang, header argument: Extracting Source Code. - (line 83) -* shell links: External Links. (line 6) -* shift-selection: Conflicts. (line 6) -* shift-selection-mode: Plain Lists. (line 95) -* show all, command: Global and local cycling. - (line 40) -* show all, global visibility state: Global and local cycling. - (line 20) -* show branches, command: Global and local cycling. - (line 52) -* show children, command: Global and local cycling. - (line 55) -* show hidden text: Visibility Cycling. (line 6) -* shy hyphen, special symbol: Special Symbols. (line 36) -* sitemap, of published pages: Site map. (line 6) -* smartphone: Org Mobile. (line 6) -* sorting, of agenda items: Sorting of agenda items. - (line 6) -* sorting, of plain list: Plain Lists. (line 159) -* sorting, of subtrees: Structure Editing. (line 6) -* source block: Literal Examples. (line 38) -* source blocks, in LaTeX export: Source blocks in LaTeX export. - (line 6) -* source code, batch execution: Batch Execution. (line 6) -* source code, block structure: Structure of Code Blocks. - (line 6) -* source code, editing: Editing Source Code. (line 6) -* source code, evaluating: Evaluating Code Blocks. - (line 6) -* source code, exporting: Exporting Code Blocks. - (line 6) -* source code, extracting: Extracting Source Code. - (line 6) -* source code, inline: Structure of Code Blocks. - (line 24) -* source code, languages: Languages. (line 6) -* source code, library: Library of Babel. (line 6) -* source code, noweb reference: Noweb Reference Syntax. - (line 6) -* source code, results of evaluation: Results of Evaluation. - (line 6) -* source code, working with: Working with Source Code. - (line 6) -* sparse tree, for deadlines: Inserting deadline/schedule. - (line 26) -* sparse tree, for TODO: TODO Basics. (line 35) -* sparse tree, tag based: Tags. (line 6) -* sparse trees: Sparse Trees. (line 6) -* special blocks, in ASCII export: ASCII/Latin-1/UTF-8 export. - (line 84) -* special blocks, in LaTeX export: Special blocks in LaTeX export. - (line 6) -* special keywords: In-buffer Settings. (line 6) -* special symbols: Special Symbols. (line 6) -* special symbols, in-buffer display: Special Symbols. (line 27) -* speed keys: Speed Keys. (line 6) -* speedbar.el: Cooperation. (line 41) -* spreadsheet capabilities: The Spreadsheet. (line 6) -* square brackets, around links: External Links. (line 136) -* startup visibility: Global and local cycling. - (line 36) -* STARTUP, keyword: Initial visibility. (line 11) -* STARTUP, keyword <1>: Blocks. (line 14) -* STARTUP, keyword <2>: In-buffer Settings. (line 65) -* statistics, for checkboxes: Checkboxes. (line 29) -* statistics, for TODO items: Breaking Down Tasks. (line 6) -* store-link protocol: The store-link protocol. - (line 6) -* storing link, in a source code buffer: Literal Examples. (line 111) -* storing links: Handling Links. (line 9) -* strike-through text, markup rules: Emphasis and Monospace. - (line 6) -* structure editing: Structure Editing. (line 6) -* structure of document: Document Structure. (line 6) -* STYLE, property: Tracking your habits. - (line 6) -* styles, custom: Applying custom styles. - (line 6) -* styles, custom <1>: Advanced topics in ODT export. - (line 34) -* SUBAUTHOR, keyword: Texinfo specific export settings. - (line 14) -* SUBAUTHOR, keyword <1>: Texinfo title and copyright page. - (line 12) -* sublevels, inclusion into tags match: Tag Inheritance. (line 6) -* sublevels, inclusion into TODO list: Global TODO list. (line 38) -* subscript: Subscripts and Superscripts. - (line 6) -* SUBTITLE, keyword: ASCII/Latin-1/UTF-8 export. - (line 46) -* SUBTITLE, keyword <1>: Beamer specific export settings. - (line 44) -* SUBTITLE, keyword <2>: HTML specific export settings. - (line 56) -* SUBTITLE, keyword <3>: LaTeX specific export settings. - (line 63) -* SUBTITLE, keyword <4>: ODT specific export settings. - (line 26) -* SUBTITLE, keyword <5>: Texinfo specific export settings. - (line 11) -* subtree cycling: Global and local cycling. - (line 6) -* subtree visibility states: Global and local cycling. - (line 6) -* subtree, cut and paste: Structure Editing. (line 6) -* subtree, subtree visibility state: Global and local cycling. - (line 6) -* subtrees, cut and paste: Structure Editing. (line 6) -* summary: Summary. (line 6) -* SUMMARY, property: iCalendar Export. (line 51) -* superscript: Subscripts and Superscripts. - (line 6) -* switches, in code blocks: Structure of Code Blocks. - (line 52) -* syntax checker: Org Syntax. (line 24) -* syntax, noweb: Noweb Reference Syntax. - (line 6) -* syntax, of formulas: Formula syntax for Calc. - (line 6) -* table editor, built-in: Built-in Table Editor. - (line 6) -* table editor, table.el: Cooperation. (line 49) -* table indirection: References. (line 148) -* table lookup functions: Lookup functions. (line 6) -* table of contents: Table of Contents. (line 6) -* table of contents, exclude entries: Table of Contents. (line 15) -* table syntax: Built-in Table Editor. - (line 6) -* table-type, Texinfo attribute: Plain lists in Texinfo export. - (line 6) -* table.el: Cooperation. (line 49) -* tables: Tables. (line 6) -* tables, in HTML: Tables in HTML export. - (line 6) -* tables, in LaTeX export: Tables in LaTeX export. - (line 6) -* tables, in ODT export: Tables in ODT export. - (line 6) -* tables, in ODT export <1>: Advanced topics in ODT export. - (line 151) -* tables, in other modes: Tables in Arbitrary Syntax. - (line 6) -* tag completion: Completion. (line 6) -* tag filtering, in agenda: Filtering/limiting agenda items. - (line 20) -* tag inheritance: Tag Inheritance. (line 6) -* tag searches: Tag Searches. (line 6) -* tags: Tags. (line 6) -* tags hierarchy: Tag Hierarchy. (line 6) -* tags view: Matching tags and properties. - (line 6) -* tags, as an agenda view: Storing searches. (line 11) -* tags, groups: Tag Hierarchy. (line 6) -* TAGS, keyword: Setting Tags. (line 22) -* TAGS, keyword <1>: In-buffer Settings. (line 183) -* tags, setting: Setting Tags. (line 6) -* TAGS, special property: Special Properties. (line 13) -* tags-todo: Storing searches. (line 11) -* tags-tree: Storing searches. (line 11) -* tangle, header argument: Extracting Source Code. - (line 23) -* tangle-mode, header argument: Extracting Source Code. - (line 89) -* tangling: Extracting Source Code. - (line 6) -* targets, for links: Internal Links. (line 17) -* targets, radio: Radio Targets. (line 6) -* tasks, breaking down: Breaking Down Tasks. (line 6) -* tasks, repeated: Repeated tasks. (line 6) -* TBLFM keywords, multiple: Editing and debugging formulas. - (line 98) -* TBLFM, keyword: Field and range formulas. - (line 12) -* TBLFM, switching: Editing and debugging formulas. - (line 98) -* template expansion: Structure Templates. (line 21) -* template insertion: Structure Templates. (line 6) -* template, custom: Applying custom styles. - (line 6) -* template, custom <1>: Advanced topics in ODT export. - (line 34) -* templates, for Capture: Capture templates. (line 6) -* Tempo: Structure Templates. (line 21) -* TeX interpretation: Embedded LaTeX. (line 6) -* TeX symbol completion: Completion. (line 6) -* TEXINFO, keyword: Quoting Texinfo code. - (line 9) -* TEXINFO_CLASS, keyword: Texinfo specific export settings. - (line 20) -* TEXINFO_CLASS, keyword <1>: Texinfo file header. (line 19) -* TEXINFO_CLASS, keyword <2>: Headings and sectioning structure. - (line 6) -* TEXINFO_DIR_CATEGORY, keyword: Texinfo specific export settings. - (line 30) -* TEXINFO_DIR_CATEGORY, keyword <1>: Info directory file. (line 6) -* TEXINFO_DIR_DESC, keyword: Texinfo specific export settings. - (line 36) -* TEXINFO_DIR_DESC, keyword <1>: Info directory file. (line 6) -* TEXINFO_DIR_TITLE, keyword: Texinfo specific export settings. - (line 33) -* TEXINFO_DIR_TITLE, keyword <1>: Info directory file. (line 6) -* TEXINFO_FILENAME, keyword: Texinfo specific export settings. - (line 17) -* TEXINFO_FILENAME, keyword <1>: Texinfo file header. (line 6) -* TEXINFO_HEADER, keyword: Texinfo specific export settings. - (line 24) -* TEXINFO_HEADER, keyword <1>: Texinfo file header. (line 11) -* TEXINFO_POST_HEADER, keyword: Texinfo specific export settings. - (line 27) -* TEXINFO_PRINTED_TITLE, keyword: Texinfo specific export settings. - (line 39) -* TEXINFO_PRINTED_TITLE, keyword <1>: Texinfo title and copyright page. - (line 6) -* text areas, in HTML: Text areas in HTML export. - (line 6) -* text search: Search view. (line 6) -* time clocking: Clocking Work Time. (line 6) -* time format, custom: Custom time format. (line 6) -* time grid: Time-of-day specifications. - (line 31) -* time, computing: Durations and time values. - (line 6) -* time, macro: Macro Replacement. (line 56) -* time, reading in minibuffer: The date/time prompt. - (line 6) -* time-of-day specification: Time-of-day specifications. - (line 6) -* timerange: Timestamps. (line 42) -* times: Dates and Times. (line 6) -* timestamp: Dates and Times. (line 6) -* timestamp <1>: Timestamps. (line 14) -* timestamp, inactive: Timestamps. (line 50) -* TIMESTAMP, special property: Special Properties. (line 13) -* timestamp, with repeater interval: Timestamps. (line 25) -* timestamps: Timestamps. (line 6) -* TIMESTAMP_IA, special property: Special Properties. (line 13) -* TIMEZONE, property: iCalendar Export. (line 51) -* TINDEX, keyword: Indices. (line 6) -* TITLE, keyword: Export Settings. (line 60) -* title, macro: Macro Replacement. (line 41) -* toc, in OPTIONS keyword: Table of Contents. (line 6) -* TOC, keyword: Table of Contents. (line 24) -* TODO dependencies: TODO dependencies. (line 6) -* TODO dependencies, NOBLOCKING: TODO dependencies. (line 29) -* TODO items: TODO Items. (line 6) -* TODO keyword matching: Global TODO list. (line 18) -* TODO keyword matching, with tags search: Matching tags and properties. - (line 65) -* TODO keyword sets: Multiple sets in one file. - (line 6) -* TODO keywords completion: Completion. (line 6) -* TODO list, global: Global TODO list. (line 6) -* TODO types: TODO types. (line 6) -* TODO workflow: Workflow states. (line 6) -* todo, as an agenda view: Storing searches. (line 11) -* TODO, keyword: Per-file keywords. (line 6) -* TODO, keyword <1>: In-buffer Settings. (line 190) -* TODO, special property: Special Properties. (line 13) -* todo-tree: Storing searches. (line 11) -* top headline filtering, in agenda: Filtering/limiting agenda items. - (line 20) -* Top node, in Texinfo export: Headings and sectioning structure. - (line 37) -* transient mark mode: Structure Editing. (line 46) -* translator function: Translator functions. - (line 6) -* trees, sparse: Sparse Trees. (line 6) -* trees, visibility: Visibility Cycling. (line 6) -* tty key bindings: TTY Keys. (line 6) -* two-column tables, in Texinfo export: Plain lists in Texinfo export. - (line 6) -* types as TODO keywords: TODO types. (line 6) -* TYP_TODO, keyword: Per-file keywords. (line 6) -* TYP_TODO, keyword <1>: In-buffer Settings. (line 190) -* underlined text, markup rules: Emphasis and Monospace. - (line 6) -* undoing remote-editing events: Agenda Commands. (line 227) -* unison: Uploading Files. (line 6) -* UNNUMBERED, property: Export Settings. (line 149) -* unoconv: Extending ODT export. - (line 12) -* updating, table: Updating the table. (line 6) -* URL links: External Links. (line 6) -* Usenet links: External Links. (line 6) -* using sessions in code blocks: Environment of a Code Block. - (line 279) -* UTF-8 export: ASCII/Latin-1/UTF-8 export. - (line 6) -* var, header argument: Environment of a Code Block. - (line 9) -* variable index, in Texinfo export: Indices. (line 6) -* vectors, in table calculations: Formula syntax for Calc. - (line 14) -* verbatim blocks, in LaTeX export: Example blocks in LaTeX export. - (line 6) -* verbatim text, markup rules: Emphasis and Monospace. - (line 6) -* verse blocks: Paragraphs. (line 13) -* verse blocks, in LaTeX export: Verse blocks in LaTeX export. - (line 6) -* view file commands in agenda: Agenda Commands. (line 28) -* VINDEX, keyword: Indices. (line 6) -* viper.el: Conflicts. (line 51) -* visibility cycling: Visibility Cycling. (line 6) -* visibility cycling, drawers: Drawers. (line 6) -* VISIBILITY, property: Initial visibility. (line 20) -* visible text, printing: Sparse Trees. (line 52) -* VM links: External Links. (line 109) -* Wanderlust links: External Links. (line 109) -* weekly agenda: Weekly/daily agenda. (line 6) -* windmove.el: Conflicts. (line 60) -* workflow states as TODO keywords: Workflow states. (line 6) -* working directory, in a code block: Environment of a Code Block. - (line 309) -* wrap, header argument: Results of Evaluation. - (line 208) -* xelatex: LaTeX/PDF export commands. - (line 25) -* yasnippet.el: Conflicts. (line 74) -* zero width space: Escape Character. (line 6) -* zip: Pre-requisites for ODT export. - (line 6) - - -File: org.info, Node: Key Index, Next: Command and Function Index, Prev: Main Index, Up: Top - -E Key Index -*********** - - -* Menu: - -* !: Setting Tags. (line 127) -* ! (Agenda dispatcher): Stuck projects. (line 17) -* # (Agenda dispatcher): Stuck projects. (line 14) -* $: Agenda Commands. (line 265) -* %: Agenda Commands. (line 379) -* ': CDLaTeX mode. (line 57) -* *: Agenda Commands. (line 359) -* * (Agenda dispatcher): Agenda Dispatcher. (line 55) -* +: Agenda Commands. (line 284) -* ,: Agenda Commands. (line 279) -* -: Agenda Commands. (line 289) -* .: The date/time prompt. - (line 84) -* . <1>: Agenda Commands. (line 118) -* / (Agenda dispatcher): Agenda Dispatcher. (line 30) -* 1..9,0: Using column view. (line 35) -* :: Agenda Commands. (line 275) -* <: Using column view. (line 67) -* < <1>: The date/time prompt. - (line 84) -* < (Agenda dispatcher): Agenda Dispatcher. (line 43) -* < < (Agenda dispatcher): Agenda Dispatcher. (line 49) -* >: Using column view. (line 67) -* > <1>: The date/time prompt. - (line 84) -* > <2>: Agenda Commands. (line 328) -* ? (Agenda dispatcher): Pulling from the mobile application. - (line 39) -* [: Agenda Commands. (line 142) -* ^: CDLaTeX mode. (line 43) -* _: CDLaTeX mode. (line 43) -* `: CDLaTeX mode. (line 51) -* a: Using column view. (line 57) -* A: Agenda Commands. (line 64) -* a <1>: Agenda Commands. (line 252) -* a (Agenda dispatcher): Weekly/daily agenda. (line 10) -* b: Agenda Commands. (line 115) -* B: Agenda Commands. (line 383) -* C: Resolving idle time. (line 46) -* c: Agenda Commands. (line 447) -* c <1>: Agenda Commands. (line 450) -* C <1>: Agenda Commands. (line 481) -* C (Agenda dispatcher): Storing searches. (line 11) -* C (Capture menu: Capture templates. (line 11) -* C-#: Advanced features. (line 11) -* C-': Agenda Files. (line 26) -* C-,: Agenda Files. (line 26) -* C-.: The date/time prompt. - (line 84) -* C-0 C-c C-w: Refile and Copy. (line 46) -* C-2 C-c C-w: Refile and Copy. (line 38) -* C-3 C-c C-w: Refile and Copy. (line 41) -* C-c !: Creating Timestamps. (line 25) -* C-c #: Checkboxes. (line 98) -* C-c $: Moving subtrees. (line 10) -* C-c %: Handling Links. (line 141) -* C-c &: Handling Links. (line 146) -* C-c ': Editing and debugging formulas. - (line 37) -* C-c ' <1>: Literal Examples. (line 102) -* C-c ' <2>: Include Files. (line 63) -* C-c ' <3>: Editing Source Code. (line 6) -* C-c ' <4>: Cooperation. (line 59) -* C-c *: Structure Editing. (line 129) -* C-c * <1>: Plain Lists. (line 143) -* C-c * <2>: Updating the table. (line 14) -* C-c +: Built-in Table Editor. - (line 181) -* C-c ,: Priorities. (line 33) -* C-c -: Plain Lists. (line 131) -* C-c - <1>: Built-in Table Editor. - (line 126) -* C-c .: Creating Timestamps. (line 11) -* C-c /: Sparse Trees. (line 16) -* C-c / <1>: Conflicts. (line 51) -* C-c / /: Sparse Trees. (line 20) -* C-c / a: Inserting deadline/schedule. - (line 36) -* C-c / b: Inserting deadline/schedule. - (line 33) -* C-c / d: Inserting deadline/schedule. - (line 26) -* C-c / m: Tag Searches. (line 10) -* C-c / m <1>: Property Searches. (line 11) -* C-c / p: Property Searches. (line 29) -* C-c / r: Sparse Trees. (line 20) -* C-c / t: TODO Basics. (line 35) -* C-c ;: Comment Lines. (line 20) -* C-c <: Creating Timestamps. (line 32) -* C-c =: Column formulas. (line 33) -* C-c = <1>: Editing and debugging formulas. - (line 14) -* C-c >: Creating Timestamps. (line 35) -* C-c ?: Editing and debugging formulas. - (line 25) -* C-c @: Structure Editing. (line 66) -* C-c C-*: Plain Lists. (line 148) -* C-c C-,: Structure Templates. (line 11) -* C-c C-a: Attachment defaults and dispatcher. - (line 20) -* C-c C-a <1>: Agenda Commands. (line 300) -* C-c C-a a: Attachment defaults and dispatcher. - (line 25) -* C-c C-a b: Attachment defaults and dispatcher. - (line 35) -* C-c C-a c: Attachment defaults and dispatcher. - (line 31) -* C-c C-a d: Attachment defaults and dispatcher. - (line 61) -* C-c C-a D: Attachment defaults and dispatcher. - (line 64) -* C-c C-a f: Attachment defaults and dispatcher. - (line 55) -* C-c C-a F: Attachment defaults and dispatcher. - (line 58) -* C-c C-a l: Attachment defaults and dispatcher. - (line 31) -* C-c C-a m: Attachment defaults and dispatcher. - (line 31) -* C-c C-a n: Attachment defaults and dispatcher. - (line 39) -* C-c C-a o: Attachment defaults and dispatcher. - (line 46) -* C-c C-a O: Attachment defaults and dispatcher. - (line 52) -* C-c C-a s: Attachment defaults and dispatcher. - (line 68) -* C-c C-a S: Attachment defaults and dispatcher. - (line 73) -* C-c C-a z: Attachment defaults and dispatcher. - (line 42) -* C-c C-b: Motion. (line 18) -* C-c C-b <1>: Editing support. (line 12) -* C-c C-c: Plain Lists. (line 126) -* C-c C-c <1>: Built-in Table Editor. - (line 60) -* C-c C-c <2>: Column Width and Alignment. - (line 17) -* C-c C-c <3>: Editing and debugging formulas. - (line 45) -* C-c C-c <4>: Editing and debugging formulas. - (line 91) -* C-c C-c <5>: Editing and debugging formulas. - (line 98) -* C-c C-c <6>: Checkboxes. (line 52) -* C-c C-c <7>: Setting Tags. (line 20) -* C-c C-c <8>: Setting Tags. (line 131) -* C-c C-c <9>: Property Syntax. (line 100) -* C-c C-c <10>: Using column view. (line 26) -* C-c C-c <11>: Using column view. (line 49) -* C-c C-c <12>: Capturing column view. - (line 80) -* C-c C-c <13>: Creating Timestamps. (line 29) -* C-c C-c <14>: Clocking commands. (line 53) -* C-c C-c <15>: The clock table. (line 20) -* C-c C-c <16>: Creating Footnotes. (line 65) -* C-c C-c <17>: Evaluating Code Blocks. - (line 22) -* C-c C-c <18>: Key bindings and Useful Functions. - (line 11) -* C-c C-c <19>: The Very Busy C-c C-c Key. - (line 6) -* C-c C-c (Capture buffer): Using capture. (line 15) -* C-c C-c c: Property Syntax. (line 117) -* C-c C-c d: Property Syntax. (line 111) -* C-c C-c D: Property Syntax. (line 114) -* C-c C-c m m: Markdown Export. (line 17) -* C-c C-c m M: Markdown Export. (line 21) -* C-c C-c s: Property Syntax. (line 103) -* C-c C-d: Inserting deadline/schedule. - (line 10) -* C-c C-d <1>: Agenda Commands. (line 307) -* C-c C-e: The Export Dispatcher. - (line 16) -* C-c C-e c a: iCalendar Export. (line 43) -* C-c C-e c c: iCalendar Export. (line 47) -* C-c C-e c f: iCalendar Export. (line 39) -* C-c C-e C-a: The Export Dispatcher. - (line 28) -* C-c C-e C-b: The Export Dispatcher. - (line 46) -* C-c C-e C-s: The Export Dispatcher. - (line 52) -* C-c C-e C-v: Sparse Trees. (line 52) -* C-c C-e C-v <1>: The Export Dispatcher. - (line 64) -* C-c C-e h h: HTML export commands. - (line 7) -* C-c C-e h H: HTML export commands. - (line 13) -* C-c C-e h o: HTML export commands. - (line 7) -* C-c C-e i i: Texinfo export commands. - (line 11) -* C-c C-e i t: Texinfo export commands. - (line 7) -* C-c C-e l b: Beamer export commands. - (line 7) -* C-c C-e l B: Beamer export commands. - (line 12) -* C-c C-e l l: LaTeX/PDF export commands. - (line 7) -* C-c C-e l L: LaTeX/PDF export commands. - (line 11) -* C-c C-e l O: Beamer export commands. - (line 20) -* C-c C-e l o: LaTeX/PDF export commands. - (line 17) -* C-c C-e l P: Beamer export commands. - (line 16) -* C-c C-e l p: LaTeX/PDF export commands. - (line 14) -* C-c C-e m o: Markdown Export. (line 24) -* C-c C-e o o: ODT export commands. (line 7) -* C-c C-e o O: ODT export commands. (line 23) -* C-c C-e O o: Org Export. (line 15) -* C-c C-e O v: Org Export. (line 19) -* C-c C-e P a: Triggering Publication. - (line 19) -* C-c C-e P f: Triggering Publication. - (line 16) -* C-c C-e P p: Triggering Publication. - (line 13) -* C-c C-e P x: Triggering Publication. - (line 9) -* C-c C-e t a: ASCII/Latin-1/UTF-8 export. - (line 26) -* C-c C-e t A: ASCII/Latin-1/UTF-8 export. - (line 35) -* C-c C-e t l: ASCII/Latin-1/UTF-8 export. - (line 26) -* C-c C-e t L: ASCII/Latin-1/UTF-8 export. - (line 35) -* C-c C-e t u: ASCII/Latin-1/UTF-8 export. - (line 26) -* C-c C-e t U: ASCII/Latin-1/UTF-8 export. - (line 35) -* C-c C-f: Motion. (line 15) -* C-c C-j: Motion. (line 24) -* C-c C-k: Global and local cycling. - (line 52) -* C-c C-k (Capture buffer): Using capture. (line 31) -* C-c C-l: Handling Links. (line 71) -* C-c C-M-w: Refile and Copy. (line 55) -* C-c C-n: Motion. (line 9) -* C-c C-o: Handling Links. (line 108) -* C-c C-o <1>: Creating Timestamps. (line 40) -* C-c C-o <2>: Agenda Commands. (line 56) -* C-c C-o <3>: Creating Footnotes. (line 71) -* C-c C-o <4>: Key bindings and Useful Functions. - (line 11) -* C-c C-p: Motion. (line 12) -* C-c C-q: Editing and debugging formulas. - (line 49) -* C-c C-q <1>: Setting Tags. (line 11) -* C-c C-r: Global and local cycling. - (line 43) -* C-c C-r <1>: Editing and debugging formulas. - (line 52) -* C-c C-s: Inserting deadline/schedule. - (line 18) -* C-c C-s <1>: Agenda Commands. (line 303) -* C-c C-t: TODO Basics. (line 14) -* C-c C-t <1>: Clocking commands. (line 71) -* C-c C-u: Motion. (line 21) -* C-c C-v a: Key bindings and Useful Functions. - (line 20) -* C-c C-v b: Key bindings and Useful Functions. - (line 20) -* C-c C-v c: Key bindings and Useful Functions. - (line 20) -* C-c C-v C-a: Key bindings and Useful Functions. - (line 20) -* C-c C-v C-b: Key bindings and Useful Functions. - (line 20) -* C-c C-v C-c: Key bindings and Useful Functions. - (line 20) -* C-c C-v C-d: Key bindings and Useful Functions. - (line 20) -* C-c C-v C-e: Key bindings and Useful Functions. - (line 20) -* C-c C-v C-f: Key bindings and Useful Functions. - (line 20) -* C-c C-v C-g: Key bindings and Useful Functions. - (line 20) -* C-c C-v C-h: Key bindings and Useful Functions. - (line 20) -* C-c C-v C-i: Key bindings and Useful Functions. - (line 20) -* C-c C-v C-I: Key bindings and Useful Functions. - (line 20) -* C-c C-v C-j: Key bindings and Useful Functions. - (line 20) -* C-c C-v C-l: Key bindings and Useful Functions. - (line 20) -* C-c C-v C-n: Key bindings and Useful Functions. - (line 20) -* C-c C-v C-o: Key bindings and Useful Functions. - (line 20) -* C-c C-v C-p: Key bindings and Useful Functions. - (line 20) -* C-c C-v C-r: Key bindings and Useful Functions. - (line 20) -* C-c C-v C-s: Key bindings and Useful Functions. - (line 20) -* C-c C-v C-t: Key bindings and Useful Functions. - (line 20) -* C-c C-v C-u: Key bindings and Useful Functions. - (line 20) -* C-c C-v C-v: Noweb Reference Syntax. - (line 202) -* C-c C-v C-v <1>: Key bindings and Useful Functions. - (line 20) -* C-c C-v C-x: Key bindings and Useful Functions. - (line 20) -* C-c C-v C-z: Key bindings and Useful Functions. - (line 20) -* C-c C-v d: Key bindings and Useful Functions. - (line 20) -* C-c C-v e: Evaluating Code Blocks. - (line 22) -* C-c C-v e <1>: Key bindings and Useful Functions. - (line 20) -* C-c C-v f: Extracting Source Code. - (line 116) -* C-c C-v f <1>: Key bindings and Useful Functions. - (line 20) -* C-c C-v g: Key bindings and Useful Functions. - (line 20) -* C-c C-v h: Key bindings and Useful Functions. - (line 20) -* C-c C-v i: Library of Babel. (line 12) -* C-c C-v i <1>: Key bindings and Useful Functions. - (line 20) -* C-c C-v I: Key bindings and Useful Functions. - (line 20) -* C-c C-v j: Key bindings and Useful Functions. - (line 20) -* C-c C-v l: Key bindings and Useful Functions. - (line 20) -* C-c C-v n: Key bindings and Useful Functions. - (line 20) -* C-c C-v o: Key bindings and Useful Functions. - (line 20) -* C-c C-v p: Key bindings and Useful Functions. - (line 20) -* C-c C-v r: Key bindings and Useful Functions. - (line 20) -* C-c C-v s: Key bindings and Useful Functions. - (line 20) -* C-c C-v t: Extracting Source Code. - (line 111) -* C-c C-v t <1>: Key bindings and Useful Functions. - (line 20) -* C-c C-v u: Key bindings and Useful Functions. - (line 20) -* C-c C-v v: Noweb Reference Syntax. - (line 202) -* C-c C-v v <1>: Key bindings and Useful Functions. - (line 20) -* C-c C-v x: Key bindings and Useful Functions. - (line 20) -* C-c C-v z: Key bindings and Useful Functions. - (line 20) -* C-c C-w: Structure Editing. (line 104) -* C-c C-w <1>: Refile and Copy. (line 13) -* C-c C-w <2>: Agenda Commands. (line 249) -* C-c C-w (Capture buffer): Using capture. (line 22) -* C-c C-x ,: Timers. (line 44) -* C-c C-x -: Timers. (line 36) -* C-c C-x .: Timers. (line 32) -* C-c C-x 0: Timers. (line 13) -* C-c C-x ;: Timers. (line 23) -* C-c C-x <: Agenda Files. (line 43) -* C-c C-x >: Agenda Files. (line 52) -* C-c C-x > <1>: Agenda Commands. (line 206) -* C-c C-x @: Citations. (line 14) -* C-c C-x a: Internal archiving. (line 39) -* C-c C-x A: Internal archiving. (line 54) -* C-c C-x a <1>: Agenda Commands. (line 257) -* C-c C-x A <1>: Agenda Commands. (line 261) -* C-c C-x b: Global and local cycling. - (line 59) -* C-c C-x b <1>: Agenda Commands. (line 49) -* C-c C-x c: Structure Editing. (line 96) -* C-c C-x C-a: Archiving. (line 12) -* C-c C-x C-a <1>: Agenda Commands. (line 252) -* C-c C-x C-b: Checkboxes. (line 58) -* C-c C-x C-c: Using column view. (line 10) -* C-c C-x C-c <1>: Agenda Commands. (line 197) -* C-c C-x C-c <2>: Agenda Column View. (line 12) -* C-c C-x C-d: Clocking commands. (line 84) -* C-c C-x C-e: Clocking commands. (line 50) -* C-c C-x C-e <1>: Effort Estimates. (line 24) -* C-c C-x C-i: Clocking commands. (line 7) -* C-c C-x C-j: Clocking commands. (line 79) -* C-c C-x C-l: Previewing LaTeX fragments. - (line 18) -* C-c C-x C-n: Handling Links. (line 153) -* C-c C-x C-o: Clocking commands. (line 36) -* C-c C-x C-p: Handling Links. (line 153) -* C-c C-x C-q: Clocking commands. (line 75) -* C-c C-x C-r: Checkboxes. (line 75) -* C-c C-x C-s: Moving subtrees. (line 10) -* C-c C-x C-s <1>: Agenda Commands. (line 265) -* C-c C-x C-t: Custom time format. (line 13) -* C-c C-x C-u: Capturing column view. - (line 80) -* C-c C-x C-u <1>: The clock table. (line 20) -* C-c C-x C-u <2>: Dynamic Blocks. (line 25) -* C-c C-x C-v: Images. (line 24) -* C-c C-x C-w: Structure Editing. (line 70) -* C-c C-x C-w <1>: Built-in Table Editor. - (line 157) -* C-c C-x C-x: Clocking commands. (line 44) -* C-c C-x C-y: Structure Editing. (line 78) -* C-c C-x C-y <1>: Built-in Table Editor. - (line 161) -* C-c C-x d: Drawers. (line 18) -* C-c C-x e: Effort Estimates. (line 19) -* C-c C-x e <1>: Agenda Commands. (line 292) -* C-c C-x f: Creating Footnotes. (line 42) -* C-c C-x g: RSS Feeds. (line 23) -* C-c C-x G: RSS Feeds. (line 27) -* C-c C-x I: Documentation Access. - (line 6) -* C-c C-x M-w: Structure Editing. (line 74) -* C-c C-x M-w <1>: Built-in Table Editor. - (line 151) -* C-c C-x o: TODO dependencies. (line 38) -* C-c C-x o <1>: Checkboxes. (line 90) -* C-c C-x p: Property Syntax. (line 90) -* C-c C-x p <1>: Using Header Arguments. - (line 70) -* C-c C-x q: Tag Hierarchy. (line 87) -* C-c C-x v: Global and local cycling. - (line 65) -* C-c C-x x: Capturing column view. - (line 72) -* C-c C-x x <1>: The clock table. (line 11) -* C-c C-x x <2>: Dynamic Blocks. (line 10) -* C-c C-x \: Subscripts and Superscripts. - (line 27) -* C-c C-x \ <1>: Special Symbols. (line 31) -* C-c C-x _: Timers. (line 47) -* C-c C-y: Creating Timestamps. (line 62) -* C-c C-y <1>: Clocking commands. (line 53) -* C-c C-z: Drawers. (line 39) -* C-c C-z <1>: Agenda Commands. (line 295) -* C-c M-w: Refile and Copy. (line 51) -* C-c RET: Built-in Table Editor. - (line 130) -* C-c TAB: Global and local cycling. - (line 55) -* C-c TAB <1>: Column Width and Alignment. - (line 44) -* C-c [: Agenda Files. (line 16) -* C-c \: Tag Searches. (line 10) -* C-c \ <1>: Property Searches. (line 11) -* C-c ]: Agenda Files. (line 22) -* C-c ^: Structure Editing. (line 108) -* C-c ^ <1>: Plain Lists. (line 159) -* C-c ^ <2>: Built-in Table Editor. - (line 134) -* C-c `: Built-in Table Editor. - (line 202) -* C-c {: Editing and debugging formulas. - (line 34) -* C-c { <1>: CDLaTeX mode. (line 25) -* C-c |: Built-in Table Editor. - (line 42) -* C-c | <1>: Built-in Table Editor. - (line 221) -* C-c }: Editing and debugging formulas. - (line 29) -* C-c } <1>: Editing and debugging formulas. - (line 83) -* C-c ~: Cooperation. (line 63) -* C-g: Setting Tags. (line 121) -* C-k: Agenda Commands. (line 243) -* C-RET: Structure Editing. (line 26) -* C-S-DOWN: Clocking commands. (line 59) -* C-S-LEFT: Multiple sets in one file. - (line 28) -* C-S-LEFT <1>: Agenda Commands. (line 240) -* C-S-RET: Structure Editing. (line 33) -* C-S-RIGHT: Multiple sets in one file. - (line 28) -* C-S-RIGHT <1>: Agenda Commands. (line 237) -* C-S-UP: Clocking commands. (line 59) -* C-TAB: Internal archiving. (line 51) -* C-u C-c !: Creating Timestamps. (line 25) -* C-u C-c *: Updating the table. (line 19) -* C-u C-c .: Creating Timestamps. (line 16) -* C-u C-c =: Field and range formulas. - (line 28) -* C-u C-c = <1>: Editing and debugging formulas. - (line 14) -* C-u C-c C-c: Updating the table. (line 19) -* C-u C-c C-l: Handling Links. (line 94) -* C-u C-c C-t: Progress Logging. (line 10) -* C-u C-c C-w: Refile and Copy. (line 32) -* C-u C-c C-x a: Internal archiving. (line 44) -* C-u C-c C-x C-s: Moving subtrees. (line 14) -* C-u C-c C-x C-u: Capturing column view. - (line 84) -* C-u C-c C-x C-u <1>: The clock table. (line 24) -* C-u C-c C-x C-u <2>: Dynamic Blocks. (line 28) -* C-u C-c TAB: Column Width and Alignment. - (line 54) -* C-u C-u C-c !: Creating Timestamps. (line 25) -* C-u C-u C-c *: Updating the table. (line 24) -* C-u C-u C-c .: Creating Timestamps. (line 21) -* C-u C-u C-c =: Editing and debugging formulas. - (line 19) -* C-u C-u C-c C-c: Updating the table. (line 24) -* C-u C-u C-c C-t: Multiple sets in one file. - (line 28) -* C-u C-u C-c C-w: Refile and Copy. (line 35) -* C-u C-u C-c C-x C-s: Moving subtrees. (line 21) -* C-u C-u C-c TAB: Column Width and Alignment. - (line 57) -* C-u C-u C-u C-c C-w: Refile and Copy. (line 46) -* C-u C-u C-u C-u C-c C-t: TODO dependencies. (line 46) -* C-u C-u C-u TAB: Global and local cycling. - (line 40) -* C-u C-u TAB: Global and local cycling. - (line 36) -* C-u C-u TAB <1>: Initial visibility. (line 26) -* C-u TAB: Global and local cycling. - (line 20) -* C-v: The date/time prompt. - (line 84) -* C-x C-s: Editing and debugging formulas. - (line 45) -* C-x C-s <1>: Agenda Commands. (line 193) -* C-x C-s <2>: Editing Source Code. (line 11) -* C-x C-w: Exporting Agenda Views. - (line 13) -* C-x n b: Structure Editing. (line 123) -* C-x n s: Structure Editing. (line 120) -* C-x n w: Structure Editing. (line 126) -* C-y: Structure Editing. (line 84) -* C-_: Agenda Commands. (line 227) -* d: Agenda Commands. (line 71) -* D: Agenda Commands. (line 127) -* e: Using column view. (line 43) -* E: Agenda Commands. (line 173) -* e <1>: Agenda Commands. (line 292) -* e (Agenda dispatcher): Exporting Agenda Views. - (line 53) -* F: Agenda Commands. (line 42) -* f: Agenda Commands. (line 110) -* g: Using column view. (line 22) -* G: Agenda Commands. (line 181) -* g <1>: Agenda Commands. (line 186) -* H: Agenda Commands. (line 485) -* I: Agenda Commands. (line 332) -* i: Agenda Commands. (line 454) -* j: Agenda Commands. (line 121) -* J: Agenda Commands. (line 124) -* J <1>: Agenda Commands. (line 342) -* k: Resolving idle time. (line 23) -* K: Resolving idle time. (line 29) -* k <1>: Agenda Commands. (line 345) -* k c (Agenda): Using capture. (line 33) -* l: Agenda Commands. (line 131) -* m: Agenda Commands. (line 353) -* M: Agenda Commands. (line 472) -* m (Agenda dispatcher): Tag Searches. (line 15) -* M (Agenda dispatcher): Tag Searches. (line 19) -* m (Agenda dispatcher) <1>: Property Searches. (line 15) -* M (Agenda dispatcher) <1>: Property Searches. (line 18) -* m (Agenda dispatcher) <2>: Matching tags and properties. - (line 13) -* M (Agenda dispatcher) <2>: Matching tags and properties. - (line 21) -* M-*: Agenda Commands. (line 375) -* M-a: Built-in Table Editor. - (line 78) -* M-DOWN: Structure Editing. (line 63) -* M-DOWN <1>: Plain Lists. (line 102) -* M-DOWN <2>: Built-in Table Editor. - (line 104) -* M-DOWN <3>: Editing and debugging formulas. - (line 80) -* M-DOWN <4>: Agenda Commands. (line 217) -* M-DOWN <5>: Key bindings and Useful Functions. - (line 11) -* M-e: Built-in Table Editor. - (line 82) -* M-g M-n: Sparse Trees. (line 32) -* M-g M-p: Sparse Trees. (line 35) -* M-g n: Sparse Trees. (line 32) -* M-g p: Sparse Trees. (line 35) -* M-LEFT: Structure Editing. (line 44) -* M-LEFT <1>: Plain Lists. (line 108) -* M-LEFT <2>: Built-in Table Editor. - (line 88) -* M-m: Agenda Commands. (line 371) -* M-RET: Structure Editing. (line 7) -* M-RET <1>: Plain Lists. (line 83) -* M-RET <2>: Built-in Table Editor. - (line 168) -* M-RET <3>: Timers. (line 40) -* M-RIGHT: Structure Editing. (line 44) -* M-RIGHT <1>: Plain Lists. (line 108) -* M-RIGHT <2>: Built-in Table Editor. - (line 91) -* M-S-DOWN: Built-in Table Editor. - (line 122) -* M-S-DOWN <1>: Editing and debugging formulas. - (line 74) -* M-S-LEFT: Structure Editing. (line 54) -* M-S-LEFT <1>: Plain Lists. (line 113) -* M-S-LEFT <2>: Built-in Table Editor. - (line 94) -* M-S-LEFT <3>: The date/time prompt. - (line 84) -* M-S-RET: Structure Editing. (line 29) -* M-S-RET <1>: Plain Lists. (line 91) -* M-S-RET <2>: Checkboxes. (line 86) -* M-S-RIGHT: Structure Editing. (line 57) -* M-S-RIGHT <1>: Plain Lists. (line 113) -* M-S-RIGHT <2>: Built-in Table Editor. - (line 97) -* M-S-RIGHT <3>: The date/time prompt. - (line 84) -* M-S-UP: Built-in Table Editor. - (line 107) -* M-S-UP <1>: Editing and debugging formulas. - (line 71) -* M-TAB: Editing and debugging formulas. - (line 63) -* M-TAB <1>: Per-file keywords. (line 26) -* M-TAB <2>: Setting Tags. (line 6) -* M-TAB <3>: Property Syntax. (line 86) -* M-TAB <4>: Completion. (line 15) -* M-UP: Structure Editing. (line 60) -* M-UP <1>: Plain Lists. (line 102) -* M-UP <2>: Built-in Table Editor. - (line 101) -* M-UP <3>: Editing and debugging formulas. - (line 77) -* M-UP <4>: Agenda Commands. (line 210) -* M-UP <5>: Key bindings and Useful Functions. - (line 11) -* M-v: The date/time prompt. - (line 84) -* mouse-1: Handling Links. (line 133) -* mouse-1 <1>: The date/time prompt. - (line 84) -* mouse-1 <2>: Creating Footnotes. (line 71) -* mouse-2: Handling Links. (line 133) -* mouse-2 <1>: Agenda Commands. (line 36) -* mouse-2 <2>: Creating Footnotes. (line 71) -* mouse-3: Handling Links. (line 137) -* mouse-3 <1>: Agenda Commands. (line 29) -* n: Using column view. (line 39) -* n <1>: Agenda Commands. (line 20) -* o: Agenda Commands. (line 68) -* O: Agenda Commands. (line 336) -* p: Using column view. (line 39) -* p <1>: Agenda Commands. (line 23) -* q: Setting Tags. (line 124) -* q <1>: Using column view. (line 26) -* q <2>: Agenda Commands. (line 491) -* r: Using column view. (line 22) -* r <1>: Global TODO list. (line 25) -* R: Agenda Commands. (line 154) -* r <2>: Agenda Commands. (line 186) -* RET: Built-in Table Editor. - (line 73) -* RET <1>: Handling Links. (line 129) -* RET <2>: Setting Tags. (line 118) -* RET <3>: The date/time prompt. - (line 84) -* RET <4>: Agenda Commands. (line 39) -* s: Resolving idle time. (line 35) -* S: Resolving idle time. (line 40) -* s <1>: Agenda Commands. (line 193) -* S <1>: Agenda Commands. (line 476) -* s (Agenda dispatcher): Agenda Dispatcher. (line 25) -* s (Agenda dispatcher) <1>: Search view. (line 10) -* S-DOWN: Plain Lists. (line 95) -* S-DOWN <1>: Built-in Table Editor. - (line 113) -* S-DOWN <2>: Editing and debugging formulas. - (line 66) -* S-DOWN <3>: Priorities. (line 41) -* S-DOWN <4>: Creating Timestamps. (line 50) -* S-DOWN <5>: The date/time prompt. - (line 84) -* S-DOWN <6>: Agenda Commands. (line 289) -* S-LEFT: Plain Lists. (line 154) -* S-LEFT <1>: Built-in Table Editor. - (line 116) -* S-LEFT <2>: Editing and debugging formulas. - (line 66) -* S-LEFT <3>: TODO Basics. (line 28) -* S-LEFT <4>: Multiple sets in one file. - (line 36) -* S-LEFT <5>: Property Syntax. (line 108) -* S-LEFT <6>: Using column view. (line 39) -* S-LEFT <7>: Creating Timestamps. (line 45) -* S-LEFT <8>: The date/time prompt. - (line 84) -* S-LEFT <9>: The clock table. (line 29) -* S-LEFT <10>: Agenda Commands. (line 324) -* S-M-DOWN: Clocking commands. (line 64) -* S-M-LEFT: Using column view. (line 73) -* S-M-RET: TODO Basics. (line 54) -* S-M-RIGHT: Using column view. (line 70) -* S-M-UP: Clocking commands. (line 64) -* S-RET: Built-in Table Editor. - (line 186) -* S-RIGHT: Plain Lists. (line 154) -* S-RIGHT <1>: Built-in Table Editor. - (line 119) -* S-RIGHT <2>: Editing and debugging formulas. - (line 66) -* S-RIGHT <3>: TODO Basics. (line 28) -* S-RIGHT <4>: Multiple sets in one file. - (line 36) -* S-RIGHT <5>: Property Syntax. (line 108) -* S-RIGHT <6>: Using column view. (line 39) -* S-RIGHT <7>: Creating Timestamps. (line 45) -* S-RIGHT <8>: The date/time prompt. - (line 84) -* S-RIGHT <9>: The clock table. (line 29) -* S-RIGHT <10>: Agenda Commands. (line 311) -* S-TAB: Global and local cycling. - (line 20) -* S-TAB <1>: Built-in Table Editor. - (line 70) -* S-UP: Plain Lists. (line 95) -* S-UP <1>: Built-in Table Editor. - (line 110) -* S-UP <2>: Editing and debugging formulas. - (line 66) -* S-UP <3>: Priorities. (line 41) -* S-UP <4>: Creating Timestamps. (line 50) -* S-UP <5>: The date/time prompt. - (line 84) -* S-UP <6>: Agenda Commands. (line 284) -* SPC: Setting Tags. (line 115) -* SPC <1>: Agenda Commands. (line 29) -* t: Agenda Commands. (line 231) -* T: Agenda Commands. (line 270) -* t (Agenda dispatcher): TODO Basics. (line 46) -* t (Agenda dispatcher) <1>: Global TODO list. (line 10) -* T (Agenda dispatcher): Global TODO list. (line 18) -* TAB: Global and local cycling. - (line 11) -* TAB <1>: Structure Editing. (line 37) -* TAB <2>: Plain Lists. (line 70) -* TAB <3>: Built-in Table Editor. - (line 63) -* TAB <4>: Editing and debugging formulas. - (line 56) -* TAB <5>: Setting Tags. (line 108) -* TAB <6>: Agenda Commands. (line 36) -* TAB <7>: CDLaTeX mode. (line 29) -* u: Agenda Commands. (line 363) -* U: Agenda Commands. (line 367) -* v: Using column view. (line 53) -* v a: Agenda Commands. (line 146) -* v A: Agenda Commands. (line 151) -* v c: Agenda Commands. (line 165) -* v d: Agenda Commands. (line 71) -* v E: Agenda Commands. (line 173) -* v l: Agenda Commands. (line 131) -* v L: Agenda Commands. (line 131) -* v m: Agenda Commands. (line 91) -* v R: Agenda Commands. (line 154) -* v SPC: Agenda Commands. (line 107) -* v w: Agenda Commands. (line 81) -* v y: Agenda Commands. (line 101) -* v [: Agenda Commands. (line 142) -* w: Agenda Commands. (line 81) -* X: Agenda Commands. (line 339) -* x: Agenda Commands. (line 495) -* z: Agenda Commands. (line 295) - - -File: org.info, Node: Command and Function Index, Next: Variable Index, Prev: Key Index, Up: Top - -F Command and Function Index -**************************** - - -* Menu: - -* lisp-complete-symbol: Editing and debugging formulas. - (line 63) -* next-error: Sparse Trees. (line 32) -* or-clock-goto: Clocking commands. (line 79) -* org-agenda: Activation. (line 13) -* org-agenda-add-note: Agenda Commands. (line 295) -* org-agenda-archive: Agenda Commands. (line 265) -* org-agenda-archive-default-with-confirmation: Agenda Commands. - (line 252) -* org-agenda-archive-to-archive-sibling: Agenda Commands. (line 261) -* org-agenda-archives-mode: Agenda Commands. (line 146) -* org-agenda-bulk-action: Agenda Commands. (line 383) -* org-agenda-bulk-mark: Agenda Commands. (line 353) -* org-agenda-bulk-mark-all: Agenda Commands. (line 359) -* org-agenda-bulk-mark-regexp: Agenda Commands. (line 379) -* org-agenda-bulk-remove-all-marks: Agenda Commands. (line 367) -* org-agenda-bulk-toggle: Agenda Commands. (line 371) -* org-agenda-bulk-toggle-all: Agenda Commands. (line 375) -* org-agenda-bulk-unmark: Agenda Commands. (line 363) -* org-agenda-capture: Agenda Commands. (line 345) -* org-agenda-clock-cancel: Agenda Commands. (line 339) -* org-agenda-clock-goto: Agenda Commands. (line 124) -* org-agenda-clock-goto <1>: Agenda Commands. (line 342) -* org-agenda-clock-in: Agenda Commands. (line 332) -* org-agenda-clock-out: Agenda Commands. (line 336) -* org-agenda-clockreport-mode: Agenda Commands. (line 154) -* org-agenda-columns: Agenda Commands. (line 197) -* org-agenda-columns <1>: Agenda Column View. (line 12) -* org-agenda-convert-date: Agenda Commands. (line 481) -* org-agenda-date-prompt: Agenda Commands. (line 328) -* org-agenda-day-view: Agenda Commands. (line 71) -* org-agenda-deadline: Agenda Commands. (line 307) -* org-agenda-diary-entry: Agenda Commands. (line 454) -* org-agenda-do-date-earlier: Agenda Commands. (line 324) -* org-agenda-do-date-later: Agenda Commands. (line 311) -* org-agenda-drag-line-backward: Agenda Commands. (line 210) -* org-agenda-drag-line-forward: Agenda Commands. (line 217) -* org-agenda-earlier: Agenda Commands. (line 115) -* org-agenda-entry-text-mode: Agenda Commands. (line 173) -* org-agenda-exit: Agenda Commands. (line 495) -* org-agenda-file-to-front: Agenda Files. (line 16) -* org-agenda-filter: Filtering/limiting agenda items. - (line 73) -* org-agenda-filter-by-category: Filtering/limiting agenda items. - (line 38) -* org-agenda-filter-by-effort: Filtering/limiting agenda items. - (line 49) -* org-agenda-filter-by-regexp: Filtering/limiting agenda items. - (line 44) -* org-agenda-filter-by-tag: Filtering/limiting agenda items. - (line 28) -* org-agenda-filter-by-top-headline: Filtering/limiting agenda items. - (line 68) -* org-agenda-follow-mode: Agenda Commands. (line 42) -* org-agenda-goto: Agenda Commands. (line 36) -* org-agenda-goto-calendar: Agenda Commands. (line 447) -* org-agenda-goto-date: Agenda Commands. (line 121) -* org-agenda-goto-today: Agenda Commands. (line 118) -* org-agenda-holidays: Agenda Commands. (line 485) -* org-agenda-kill: Agenda Commands. (line 243) -* org-agenda-later: Agenda Commands. (line 110) -* org-agenda-limit-interactively: Filtering/limiting agenda items. - (line 165) -* org-agenda-list: Weekly/daily agenda. (line 10) -* org-agenda-list-stuck-projects: Stuck projects. (line 14) -* org-agenda-log-mode: Agenda Commands. (line 131) -* org-agenda-manipulate-query-add: Agenda Commands. (line 142) -* org-agenda-month-view: Agenda Commands. (line 91) -* org-agenda-next-line: Agenda Commands. (line 20) -* org-agenda-open-link: Agenda Commands. (line 56) -* org-agenda-phases-of-moon: Agenda Commands. (line 472) -* org-agenda-previous-line: Agenda Commands. (line 23) -* org-agenda-priority: Agenda Commands. (line 279) -* org-agenda-priority-down: Agenda Commands. (line 289) -* org-agenda-priority-up: Agenda Commands. (line 284) -* org-agenda-quit: Agenda Commands. (line 491) -* org-agenda-recenter: Agenda Commands. (line 33) -* org-agenda-redo: Agenda Commands. (line 186) -* org-agenda-refile: Agenda Commands. (line 249) -* org-agenda-remove-restriction-lock: Agenda Files. (line 52) -* org-agenda-remove-restriction-lock <1>: Agenda Files. (line 65) -* org-agenda-remove-restriction-lock <2>: Agenda Commands. (line 206) -* org-agenda-reset-view: Agenda Commands. (line 107) -* org-agenda-schedule: Agenda Commands. (line 303) -* org-agenda-set-effort: Agenda Commands. (line 292) -* org-agenda-set-restriction-lock: Agenda Files. (line 43) -* org-agenda-set-tags: Agenda Commands. (line 275) -* org-agenda-show-and-scroll-up: Agenda Commands. (line 29) -* org-agenda-show-tags: Agenda Commands. (line 270) -* org-agenda-sunrise-sunset: Agenda Commands. (line 476) -* org-agenda-switch-to: Agenda Commands. (line 39) -* org-agenda-todo: Agenda Commands. (line 231) -* org-agenda-todo-nextset: Agenda Commands. (line 237) -* org-agenda-toggle-archive-tag: Agenda Commands. (line 257) -* org-agenda-toggle-diary: Agenda Commands. (line 127) -* org-agenda-tree-to-indirect-buffer: Agenda Commands. (line 49) -* org-agenda-undo: Agenda Commands. (line 227) -* org-agenda-week-view: Agenda Commands. (line 81) -* org-agenda-write: Exporting Agenda Views. - (line 13) -* org-agenda-year-view: Agenda Commands. (line 101) -* org-archive-subtree: Moving subtrees. (line 10) -* org-archive-subtree-default: Archiving. (line 12) -* org-archive-to-archive-sibling: Internal archiving. (line 54) -* org-ascii-convert-region-to-ascii: Export in Foreign Buffers. - (line 11) -* org-ascii-convert-region-to-utf8: Export in Foreign Buffers. - (line 14) -* org-ascii-export-as-ascii: ASCII/Latin-1/UTF-8 export. - (line 35) -* org-ascii-export-to-ascii: ASCII/Latin-1/UTF-8 export. - (line 26) -* org-attach: Attachment defaults and dispatcher. - (line 20) -* org-attach <1>: Agenda Commands. (line 300) -* org-attach-attach: Attachment defaults and dispatcher. - (line 25) -* org-attach-buffer: Attachment defaults and dispatcher. - (line 35) -* org-attach-dired-to-subtree: Attach from Dired. (line 6) -* org-attach-new: Attachment defaults and dispatcher. - (line 39) -* org-attach-open: Attachment defaults and dispatcher. - (line 46) -* org-attach-open-in-emacs: Attachment defaults and dispatcher. - (line 52) -* org-attach-reveal: Attachment defaults and dispatcher. - (line 55) -* org-attach-reveal-in-emacs: Attachment defaults and dispatcher. - (line 58) -* org-attach-sync: Attachment defaults and dispatcher. - (line 42) -* org-babel-check-src-block: Key bindings and Useful Functions. - (line 20) -* org-babel-demarcate-block: Key bindings and Useful Functions. - (line 20) -* org-babel-describe-bindings: Key bindings and Useful Functions. - (line 20) -* org-babel-do-key-sequence-in-edit-buffer: Key bindings and Useful Functions. - (line 20) -* org-babel-execute-buffer: Key bindings and Useful Functions. - (line 20) -* org-babel-execute-maybe: Key bindings and Useful Functions. - (line 20) -* org-babel-execute-src-block: Evaluating Code Blocks. - (line 22) -* org-babel-execute-src-block <1>: Key bindings and Useful Functions. - (line 11) -* org-babel-execute-subtree: Key bindings and Useful Functions. - (line 20) -* org-babel-expand-src-block: Noweb Reference Syntax. - (line 202) -* org-babel-expand-src-block <1>: Key bindings and Useful Functions. - (line 20) -* org-babel-goto-named-result: Key bindings and Useful Functions. - (line 20) -* org-babel-goto-named-src-block: Key bindings and Useful Functions. - (line 20) -* org-babel-goto-src-block-head: Key bindings and Useful Functions. - (line 20) -* org-babel-insert-header-arg: Key bindings and Useful Functions. - (line 20) -* org-babel-load-in-session: Key bindings and Useful Functions. - (line 11) -* org-babel-load-in-session <1>: Key bindings and Useful Functions. - (line 20) -* org-babel-lob-ingest: Library of Babel. (line 12) -* org-babel-lob-ingest <1>: Key bindings and Useful Functions. - (line 20) -* org-babel-next-src-block: Key bindings and Useful Functions. - (line 20) -* org-babel-open-src-block-result: Key bindings and Useful Functions. - (line 11) -* org-babel-open-src-block-result <1>: Key bindings and Useful Functions. - (line 20) -* org-babel-pop-to-session: Key bindings and Useful Functions. - (line 11) -* org-babel-previous-src-block: Key bindings and Useful Functions. - (line 20) -* org-babel-sha1-hash: Key bindings and Useful Functions. - (line 20) -* org-babel-switch-to-session-with-code: Key bindings and Useful Functions. - (line 20) -* org-babel-tangle: Extracting Source Code. - (line 111) -* org-babel-tangle <1>: Key bindings and Useful Functions. - (line 20) -* org-babel-tangle-file: Extracting Source Code. - (line 116) -* org-babel-tangle-file <1>: Key bindings and Useful Functions. - (line 20) -* org-babel-tangle-jump-to-org: Extracting Source Code. - (line 129) -* org-babel-view-src-block-info: Key bindings and Useful Functions. - (line 20) -* org-backward-heading-same-level: Motion. (line 18) -* org-batch-agenda: Extracting Agenda Information. - (line 10) -* org-batch-agenda-csv: Extracting Agenda Information. - (line 41) -* org-bbdb-anniversaries: Weekly/daily agenda. (line 78) -* org-bbdb-anniversaries-future: Weekly/daily agenda. (line 109) -* org-beamer-export-as-latex: Beamer export commands. - (line 12) -* org-beamer-export-to-latex: Beamer export commands. - (line 7) -* org-beamer-export-to-pdf: Beamer export commands. - (line 16) -* org-beamer-select-environment: Editing support. (line 12) -* org-buffer-property-keys: Using the Property API. - (line 34) -* org-calendar-goto-agenda: Agenda Commands. (line 450) -* org-capture: Activation. (line 13) -* org-capture <1>: Using capture. (line 7) -* org-capture-finalize: Using capture. (line 15) -* org-capture-kill: Using capture. (line 31) -* org-capture-refile: Using capture. (line 22) -* org-check-after-date: Inserting deadline/schedule. - (line 36) -* org-check-before-date: Inserting deadline/schedule. - (line 33) -* org-check-deadlines: Inserting deadline/schedule. - (line 26) -* org-cite-insert: Citations. (line 14) -* org-clock-cancel: Clocking commands. (line 75) -* org-clock-display: Clocking commands. (line 84) -* org-clock-in: Clocking commands. (line 7) -* org-clock-in-last: Clocking commands. (line 44) -* org-clock-modify-effort-estimate: Clocking commands. (line 50) -* org-clock-modify-effort-estimate <1>: Effort Estimates. (line 24) -* org-clock-out: Clocking commands. (line 36) -* org-clock-report: The clock table. (line 11) -* org-clock-timestamp-down: Clocking commands. (line 64) -* org-clock-timestamp-up: Clocking commands. (line 64) -* org-clock-timestamps-down: Clocking commands. (line 59) -* org-clock-timestamps-up: Clocking commands. (line 59) -* org-clocktable-try-shift: The clock table. (line 29) -* org-clocktable-write-default: The clock table. (line 118) -* org-clone-subtree-with-time-shift: Structure Editing. (line 96) -* org-columns-delete: Using column view. (line 73) -* org-columns-edit-allowed: Using column view. (line 57) -* org-columns-edit-value: Using column view. (line 43) -* org-columns-insert-dblock: Capturing column view. - (line 72) -* org-columns-narrow: Using column view. (line 67) -* org-columns-new: Using column view. (line 70) -* org-columns-next-allowed-value: Using column view. (line 39) -* org-columns-previous-allowed-value: Using column view. (line 39) -* org-columns-quit: Using column view. (line 26) -* org-columns-redo: Using column view. (line 22) -* org-columns-show-value: Using column view. (line 53) -* org-columns-toggle-or-columns-quit: Using column view. (line 49) -* org-columns-widen: Using column view. (line 67) -* org-compute-property-at-point: Property Syntax. (line 117) -* org-copy-subtree: Structure Editing. (line 74) -* org-copy-visible: Global and local cycling. - (line 65) -* org-cut-subtree: Structure Editing. (line 70) -* org-cycle: Global and local cycling. - (line 11) -* org-cycle <1>: Structure Editing. (line 37) -* org-cycle <2>: Plain Lists. (line 70) -* org-cycle-agenda-files: Agenda Files. (line 26) -* org-date-from-calendar: Creating Timestamps. (line 32) -* org-dblock-update: Capturing column view. - (line 80) -* org-dblock-update <1>: The clock table. (line 20) -* org-dblock-update <2>: Dynamic Blocks. (line 25) -* org-deadline: Inserting deadline/schedule. - (line 10) -* org-delete-property: Property Syntax. (line 111) -* org-delete-property-globally: Property Syntax. (line 114) -* org-demote: Using the Mapping API. - (line 93) -* org-demote-subtree: Structure Editing. (line 57) -* org-do-demote: Structure Editing. (line 44) -* org-do-promote: Structure Editing. (line 44) -* org-dynamic-block-insert-dblock: Dynamic Blocks. (line 10) -* org-edit-special: Literal Examples. (line 102) -* org-edit-special <1>: Include Files. (line 63) -* org-edit-special <2>: Cooperation. (line 59) -* org-entities-help: Special Symbols. (line 16) -* org-entry-add-to-multivalued-property: Using the Property API. - (line 49) -* org-entry-delete: Using the Property API. - (line 28) -* org-entry-get: Using the Property API. - (line 19) -* org-entry-get-multivalued-property: Using the Property API. - (line 45) -* org-entry-member-in-multivalued-property: Using the Property API. - (line 58) -* org-entry-properties: Using the Property API. - (line 9) -* org-entry-put: Using the Property API. - (line 31) -* org-entry-put-multivalued-property: Using the Property API. - (line 40) -* org-entry-remove-from-multivalued-property: Using the Property API. - (line 53) -* org-evaluate-time-range: Creating Timestamps. (line 62) -* org-evaluate-time-range <1>: Clocking commands. (line 53) -* org-export: The Export Dispatcher. - (line 16) -* org-export-define-backend: Adding Export Back-ends. - (line 10) -* org-export-define-derived-backend: Adding Export Back-ends. - (line 10) -* org-export-to-odt: ODT export commands. (line 7) -* org-forward-heading-same-level: Motion. (line 15) -* org-global-cycle: Global and local cycling. - (line 20) -* org-goto: Motion. (line 24) -* org-goto-calendar: Creating Timestamps. (line 35) -* org-html-convert-region-to-html: Export in Foreign Buffers. - (line 17) -* org-html-export-as-html: HTML export commands. - (line 13) -* org-html-export-to-html: HTML export commands. - (line 7) -* org-icalendar-combine-agenda-files: iCalendar Export. (line 47) -* org-icalendar-export-agenda-files: iCalendar Export. (line 43) -* org-icalendar-export-to-ics: iCalendar Export. (line 39) -* org-indent-mode: Org Indent Mode. (line 6) -* org-info-find-node: Documentation Access. - (line 6) -* org-insert-drawer: Drawers. (line 18) -* org-insert-drawer <1>: Property Syntax. (line 94) -* org-insert-heading: Plain Lists. (line 83) -* org-insert-heading <1>: Timers. (line 40) -* org-insert-heading-respect-content: Structure Editing. (line 26) -* org-insert-link: Handling Links. (line 71) -* org-insert-link-global: Using Links Outside Org. - (line 6) -* org-insert-property-drawer: Using the Property API. - (line 19) -* org-insert-property-drawer <1>: Using the Property API. - (line 37) -* org-insert-structure-template: Structure Templates. (line 11) -* org-insert-todo-heading: Structure Editing. (line 29) -* org-insert-todo-heading <1>: TODO Basics. (line 54) -* org-insert-todo-heading <2>: Checkboxes. (line 86) -* org-insert-todo-heading-respect-content: Structure Editing. (line 33) -* org-latex-convert-region-to-latex: Export in Foreign Buffers. - (line 20) -* org-latex-export-as-latex: LaTeX/PDF export commands. - (line 11) -* org-latex-export-to-latex~: LaTeX/PDF export commands. - (line 7) -* org-latex-export-to-pdf: LaTeX/PDF export commands. - (line 14) -* org-latex-preview: Previewing LaTeX fragments. - (line 18) -* org-link-escape: Link Format. (line 25) -* org-link-set-parameters: Adding Hyperlink Types. - (line 74) -* org-lint: Org Syntax. (line 24) -* org-list-checkbox-radio-mode: Checkboxes. (line 81) -* org-lookup-all: Lookup functions. (line 23) -* org-lookup-first: Lookup functions. (line 9) -* org-lookup-last: Lookup functions. (line 19) -* org-map-entries: Using the Mapping API. - (line 12) -* org-mark-ring-goto: Handling Links. (line 146) -* org-mark-ring-push: Handling Links. (line 141) -* org-mark-subtree: Structure Editing. (line 66) -* org-match-sparse-tree: Tag Searches. (line 10) -* org-match-sparse-tree <1>: Property Searches. (line 11) -* org-md-convert-region-to-md: Export in Foreign Buffers. - (line 26) -* org-md-export-as-markdown: Markdown Export. (line 21) -* org-md-export-to-markdown: Markdown Export. (line 17) -* org-meta-return: Structure Editing. (line 7) -* org-mobile-pull: Pulling from the mobile application. - (line 6) -* org-mobile-push: Pushing to the mobile application. - (line 6) -* org-move-subtree-down: Structure Editing. (line 63) -* org-move-subtree-up: Structure Editing. (line 60) -* org-narrow-to-block: Structure Editing. (line 123) -* org-narrow-to-block <1>: Dynamic Blocks. (line 58) -* org-narrow-to-subtree: Structure Editing. (line 120) -* org-next-link: Handling Links. (line 153) -* org-next-visible-heading: Motion. (line 9) -* org-occur: Sparse Trees. (line 20) -* org-odt-convert: Extending ODT export. - (line 37) -* org-open-at-point: Handling Links. (line 108) -* org-open-at-point <1>: Creating Timestamps. (line 40) -* org-open-at-point-global: Using Links Outside Org. - (line 6) -* org-org-export-to-org: Org Export. (line 15) -* org-paste-subtree: Structure Editing. (line 78) -* org-previous-link: Handling Links. (line 153) -* org-previous-visible-heading: Motion. (line 12) -* org-priority: Priorities. (line 33) -* org-priority <1>: Using the Mapping API. - (line 81) -* org-priority-down: Priorities. (line 41) -* org-priority-up: Priorities. (line 41) -* org-promote: Using the Mapping API. - (line 90) -* org-promote-subtree: Structure Editing. (line 54) -* org-property-action: Property Syntax. (line 100) -* org-protocol-create: The open-source protocol. - (line 67) -* org-protocol-create-for-org: The open-source protocol. - (line 67) -* org-publish: Triggering Publication. - (line 9) -* org-publish-all: Triggering Publication. - (line 19) -* org-publish-current-file: Triggering Publication. - (line 16) -* org-publish-current-project: Triggering Publication. - (line 13) -* org-publish-find-date: Site map. (line 21) -* org-publish-find-property: Site map. (line 21) -* org-publish-find-title: Site map. (line 21) -* org-refile: Structure Editing. (line 104) -* org-refile <1>: Refile and Copy. (line 13) -* org-refile-cache-clear: Refile and Copy. (line 46) -* org-refile-copy: Refile and Copy. (line 51) -* org-refile-goto-last-stored: Refile and Copy. (line 35) -* org-refile-reverse: Refile and Copy. (line 55) -* org-remove-file: Agenda Files. (line 22) -* org-reveal: Global and local cycling. - (line 43) -* org-save-all-org-buffers: Agenda Commands. (line 193) -* org-schedule: Inserting deadline/schedule. - (line 18) -* org-search-view: Search view. (line 10) -* org-set-effort: Effort Estimates. (line 19) -* org-set-property: Property Syntax. (line 90) -* org-set-property <1>: Property Syntax. (line 103) -* org-set-property <2>: Using Header Arguments. - (line 70) -* org-set-startup-visibility: Global and local cycling. - (line 36) -* org-set-startup-visibility <1>: Initial visibility. (line 26) -* org-set-tags-command: Setting Tags. (line 11) -* org-show-todo-tree: TODO Basics. (line 35) -* org-sort: Structure Editing. (line 108) -* org-sparse-tree: Sparse Trees. (line 16) -* org-speed-command-help: Speed Keys. (line 18) -* org-speedbar-set-agenda-restriction: Agenda Files. (line 58) -* org-store-agenda-views: Exporting Agenda Views. - (line 53) -* org-store-link: Activation. (line 13) -* org-store-link <1>: Handling Links. (line 9) -* org-submit-bug-report: Feedback. (line 16) -* org-switchb: Agenda Files. (line 29) -* org-table-align: Built-in Table Editor. - (line 60) -* org-table-align <1>: Column Width and Alignment. - (line 17) -* org-table-beginning-of-field: Built-in Table Editor. - (line 78) -* org-table-blank-field: Built-in Table Editor. - (line 67) -* org-table-copy-down: Built-in Table Editor. - (line 186) -* org-table-copy-region: Built-in Table Editor. - (line 151) -* org-table-create-or-convert-from-region: Built-in Table Editor. - (line 42) -* org-table-create-or-convert-from-region <1>: Built-in Table Editor. - (line 221) -* org-table-create-with-table.el: Cooperation. (line 63) -* org-table-cut-region: Built-in Table Editor. - (line 157) -* org-table-delete-column: Built-in Table Editor. - (line 94) -* org-table-edit-field: Built-in Table Editor. - (line 202) -* org-table-edit-formulas: Editing and debugging formulas. - (line 37) -* org-table-end-of-field: Built-in Table Editor. - (line 82) -* org-table-eval-formula: Field and range formulas. - (line 28) -* org-table-eval-formula <1>: Column formulas. (line 33) -* org-table-eval-formula <2>: Editing and debugging formulas. - (line 14) -* org-table-eval-formula <3>: Editing and debugging formulas. - (line 19) -* org-table-expand: Column Width and Alignment. - (line 57) -* org-table-export: Built-in Table Editor. - (line 226) -* org-table-fedit-abort: Editing and debugging formulas. - (line 49) -* org-table-fedit-finish: Editing and debugging formulas. - (line 45) -* org-table-fedit-line-down: Editing and debugging formulas. - (line 74) -* org-table-fedit-line-up: Editing and debugging formulas. - (line 71) -* org-table-fedit-lisp-indent: Editing and debugging formulas. - (line 56) -* org-table-fedit-ref-down: Editing and debugging formulas. - (line 66) -* org-table-fedit-ref-left: Editing and debugging formulas. - (line 66) -* org-table-fedit-ref-right: Editing and debugging formulas. - (line 66) -* org-table-fedit-ref-up: Editing and debugging formulas. - (line 66) -* org-table-fedit-scroll-down: Editing and debugging formulas. - (line 80) -* org-table-fedit-scroll-up: Editing and debugging formulas. - (line 77) -* org-table-fedit-toggle-ref-type: Editing and debugging formulas. - (line 52) -* org-table-field-info: Editing and debugging formulas. - (line 25) -* org-table-header-line-mode: Built-in Table Editor. - (line 237) -* org-table-hline-and-move: Built-in Table Editor. - (line 130) -* org-table-import: Built-in Table Editor. - (line 212) -* org-table-insert-column: Built-in Table Editor. - (line 97) -* org-table-insert-hline: Built-in Table Editor. - (line 126) -* org-table-insert-row: Built-in Table Editor. - (line 122) -* org-table-iterate: Updating the table. (line 24) -* org-table-iterate-buffer-tables: Updating the table. (line 32) -* org-table-kill-row: Built-in Table Editor. - (line 107) -* org-table-move-cell-down: Built-in Table Editor. - (line 113) -* org-table-move-cell-left: Built-in Table Editor. - (line 116) -* org-table-move-cell-right: Built-in Table Editor. - (line 119) -* org-table-move-cell-up: Built-in Table Editor. - (line 110) -* org-table-move-column-left: Built-in Table Editor. - (line 88) -* org-table-move-column-right: Built-in Table Editor. - (line 91) -* org-table-move-row-down: Built-in Table Editor. - (line 104) -* org-table-move-row-up: Built-in Table Editor. - (line 101) -* org-table-next-field: Built-in Table Editor. - (line 63) -* org-table-next-row: Built-in Table Editor. - (line 73) -* org-table-paste-rectangle: Built-in Table Editor. - (line 161) -* org-table-previous-field: Built-in Table Editor. - (line 70) -* org-table-recalculate: Updating the table. (line 14) -* org-table-recalculate-buffer-tables: Updating the table. (line 29) -* org-table-rotate-recalc-marks: Advanced features. (line 11) -* org-table-shrink: Column Width and Alignment. - (line 54) -* org-table-sort-lines: Built-in Table Editor. - (line 134) -* org-table-sum: Built-in Table Editor. - (line 181) -* org-table-toggle-column-width: Column Width and Alignment. - (line 44) -* org-table-toggle-coordinate-overlays: Editing and debugging formulas. - (line 29) -* org-table-toggle-coordinate-overlays <1>: Editing and debugging formulas. - (line 83) -* org-table-toggle-formula-debugger: Editing and debugging formulas. - (line 34) -* org-table-transpose-table-at-point: Built-in Table Editor. - (line 243) -* org-table-wrap-region: Built-in Table Editor. - (line 168) -* org-tags-view: Tag Searches. (line 15) -* org-tags-view <1>: Property Searches. (line 15) -* org-tags-view <2>: Matching tags and properties. - (line 13) -* org-tags-view <3>: Matching tags and properties. - (line 21) -* org-texinfo-convert-region-to-texinfo: Export in Foreign Buffers. - (line 23) -* org-texinfo-export-to-info: Texinfo export commands. - (line 11) -* org-texinfo-export-to-texinfo: Texinfo export commands. - (line 7) -* org-time-stamp: Creating Timestamps. (line 11) -* org-time-stamp-inactive: Creating Timestamps. (line 25) -* org-timer: Timers. (line 32) -* org-timer-item: Timers. (line 36) -* org-timer-pause-or-continue: Timers. (line 44) -* org-timer-set-timer: Timers. (line 23) -* org-timer-start: Timers. (line 13) -* org-timer-stop: Timers. (line 47) -* org-timestamp-down-day: Creating Timestamps. (line 45) -* org-timestamp-up-day: Creating Timestamps. (line 45) -* org-todo: Clocking commands. (line 71) -* org-todo <1>: Using the Mapping API. - (line 77) -* org-todo-list: Global TODO list. (line 10) -* org-todo-list <1>: Global TODO list. (line 18) -* org-toggle-archive-tag: Internal archiving. (line 39) -* org-toggle-checkbox: Checkboxes. (line 52) -* org-toggle-comment: Comment Lines. (line 20) -* org-toggle-heading: Structure Editing. (line 129) -* org-toggle-inline-images: Images. (line 24) -* org-toggle-ordered-property: TODO dependencies. (line 38) -* org-toggle-ordered-property <1>: Checkboxes. (line 90) -* org-toggle-pretty-entities: Subscripts and Superscripts. - (line 27) -* org-toggle-pretty-entities <1>: Special Symbols. (line 31) -* org-toggle-radio-button: Checkboxes. (line 75) -* org-toggle-sticky-agenda: Agenda Dispatcher. (line 55) -* org-toggle-tag: Using the Mapping API. - (line 85) -* org-toggle-tags-groups: Tag Hierarchy. (line 87) -* org-toggle-time-stamp-overlays: Custom time format. (line 13) -* org-tree-to-indirect-buffer: Global and local cycling. - (line 59) -* org-update-statistics-cookies: Checkboxes. (line 98) -* org-version: Feedback. (line 16) -* org-yank: Structure Editing. (line 84) -* orgtbl-ascii-draw: Org Plot. (line 144) -* orgtbl-mode: Orgtbl Mode. (line 6) -* orgtbl-to-csv: Translator functions. - (line 6) -* orgtbl-to-generic: Translator functions. - (line 6) -* orgtbl-to-html: Translator functions. - (line 6) -* orgtbl-to-latex: Translator functions. - (line 6) -* orgtbl-to-orgtbl: Translator functions. - (line 6) -* orgtbl-to-texinfo: Translator functions. - (line 6) -* orgtbl-to-tsv: Translator functions. - (line 6) -* orgtbl-to-unicode: Translator functions. - (line 6) -* outline-show-all: Global and local cycling. - (line 40) -* outline-show-branches: Global and local cycling. - (line 52) -* outline-show-children: Global and local cycling. - (line 55) -* outline-up-heading: Motion. (line 21) -* pcomplete: Property Syntax. (line 86) -* previous-error: Sparse Trees. (line 35) -* widen: Structure Editing. (line 126) - - -File: org.info, Node: Variable Index, Prev: Command and Function Index, Up: Top - -G Variable Index -**************** - -This is not a complete index of variables and faces, only the ones that -are mentioned in the manual. For a more complete list, use ‘M-x -org-customize’ and then click yourself through the tree. - - -* Menu: - -* cdlatex-simplify-sub-super-scripts: CDLaTeX mode. (line 43) -* constants-unit-system: References. (line 121) -* constants-unit-system <1>: In-buffer Settings. (line 151) -* LaTeX-verbatim-environments: A LaTeX example. (line 19) -* org-adapt-indentation: Hard indentation. (line 16) -* org-agenda-auto-exclude-function: Filtering/limiting agenda items. - (line 99) -* org-agenda-bulk-custom-functions: Agenda Commands. (line 352) -* org-agenda-bulk-custom-functions <1>: Agenda Commands. (line 431) -* org-agenda-bulk-persistent-marks: Agenda Commands. (line 383) -* org-agenda-category-filter-preset: Filtering/limiting agenda items. - (line 6) -* org-agenda-category-icon-alist: Categories. (line 16) -* org-agenda-clock-consistency-checks: Agenda Commands. (line 165) -* org-agenda-columns-add-appointments-to-effort-sum: Effort Estimates. - (line 45) -* org-agenda-confirm-kill: Agenda Commands. (line 243) -* org-agenda-custom-commands: Sparse Trees. (line 37) -* org-agenda-custom-commands <1>: Storing searches. (line 11) -* org-agenda-custom-commands <2>: Setting options. (line 6) -* org-agenda-custom-commands <3>: Extracting Agenda Information. - (line 10) -* org-agenda-custom-commands-contexts: Setting options. (line 59) -* org-agenda-diary-file: Agenda Commands. (line 460) -* org-agenda-dim-blocked-tasks: TODO dependencies. (line 48) -* org-agenda-dim-blocked-tasks <1>: Speeding Up Your Agendas. - (line 15) -* org-agenda-effort-filter-preset: Filtering/limiting agenda items. - (line 6) -* org-agenda-entry-text-maxlines: Agenda Commands. (line 173) -* org-agenda-exporter-settings: Exporting Agenda Views. - (line 14) -* org-agenda-exporter-settings <1>: Exporting Agenda Views. - (line 68) -* org-agenda-files: Agenda Files. (line 6) -* org-agenda-files <1>: Sorting of agenda items. - (line 9) -* org-agenda-inhibit-startup: Speeding Up Your Agendas. - (line 19) -* org-agenda-log-mode-items: Agenda Commands. (line 131) -* org-agenda-loop-over-headlines-in-active-region: Execute commands in the active region. - (line 13) -* org-agenda-max-effort: Filtering/limiting agenda items. - (line 136) -* org-agenda-max-entries: Filtering/limiting agenda items. - (line 133) -* org-agenda-max-tags: Filtering/limiting agenda items. - (line 142) -* org-agenda-max-todos: Filtering/limiting agenda items. - (line 139) -* org-agenda-overriding-header: Special Agenda Views. - (line 38) -* org-agenda-prefix-format: Presentation and Sorting. - (line 6) -* org-agenda-regexp-filter-preset: Filtering/limiting agenda items. - (line 6) -* org-agenda-restore-windows-after-quit: Agenda Views. (line 42) -* org-agenda-search-headline-for-time: Time-of-day specifications. - (line 16) -* org-agenda-show-inherited-tags: Agenda Commands. (line 270) -* org-agenda-show-inherited-tags <1>: Speeding Up Your Agendas. - (line 23) -* org-agenda-skip-archived-trees: Internal archiving. (line 23) -* org-agenda-skip-archived-trees <1>: Agenda Views. (line 37) -* org-agenda-skip-comment-trees: Agenda Views. (line 37) -* org-agenda-skip-deadline-prewarning-if-scheduled: Deadlines and Scheduling. - (line 24) -* org-agenda-skip-function: Special Agenda Views. - (line 6) -* org-agenda-skip-function <1>: Special Agenda Views. - (line 41) -* org-agenda-skip-function <2>: Using the Mapping API. - (line 69) -* org-agenda-skip-function-global: Special Agenda Views. - (line 6) -* org-agenda-skip-scheduled-delay-if-deadline: Deadlines and Scheduling. - (line 42) -* org-agenda-skip-scheduled-if-deadline-is-shown: Repeated tasks. - (line 80) -* org-agenda-skip-scheduled-if-done: Deadlines and Scheduling. - (line 34) -* org-agenda-sorting-strategy: Sorting of agenda items. - (line 28) -* org-agenda-span: Weekly/daily agenda. (line 15) -* org-agenda-span <1>: Agenda Commands. (line 107) -* org-agenda-start-day: Weekly/daily agenda. (line 15) -* org-agenda-start-on-weekday: Weekly/daily agenda. (line 15) -* org-agenda-start-with-clockreport-mode: Agenda Commands. (line 154) -* org-agenda-start-with-entry-text-mode: Agenda Commands. (line 173) -* org-agenda-start-with-follow-mode: Agenda Commands. (line 42) -* org-agenda-sticky: Agenda Dispatcher. (line 55) -* org-agenda-tag-filter-preset: Filtering/limiting agenda items. - (line 6) -* org-agenda-tags-column: Presentation and Sorting. - (line 6) -* org-agenda-tags-todo-honor-ignore-options: Matching tags and properties. - (line 21) -* org-agenda-text-search-extra-files: Agenda Dispatcher. (line 30) -* org-agenda-text-search-extra-files <1>: Search view. (line 34) -* org-agenda-time-grid: Time-of-day specifications. - (line 46) -* org-agenda-time-grid <1>: Agenda Commands. (line 181) -* org-agenda-todo-ignore-deadlines: Global TODO list. (line 42) -* org-agenda-todo-ignore-scheduled: Global TODO list. (line 42) -* org-agenda-todo-ignore-timestamp: Global TODO list. (line 42) -* org-agenda-todo-ignore-with-date: Global TODO list. (line 42) -* org-agenda-todo-list-sublevels: Breaking Down Tasks. (line 6) -* org-agenda-todo-list-sublevels <1>: Global TODO list. (line 53) -* org-agenda-use-tag-inheritance: Tag Inheritance. (line 32) -* org-agenda-use-tag-inheritance <1>: Speeding Up Your Agendas. - (line 23) -* org-agenda-use-time-grid: Time-of-day specifications. - (line 46) -* org-agenda-use-time-grid <1>: Agenda Commands. (line 181) -* org-agenda-window-setup: Agenda Views. (line 42) -* org-alphabetical-lists: Plain Lists. (line 15) -* org-archive-default-command: Archiving. (line 12) -* org-archive-default-command <1>: Agenda Commands. (line 252) -* org-archive-location: Moving subtrees. (line 10) -* org-archive-location <1>: In-buffer Settings. (line 15) -* org-archive-save-context-info: Moving subtrees. (line 41) -* org-archive-subtree-save-file-p: Moving subtrees. (line 47) -* org-ascii-links-to-notes: ASCII/Latin-1/UTF-8 export. - (line 16) -* org-ascii-text-width: ASCII/Latin-1/UTF-8 export. - (line 13) -* org-attach-archive-delete: Attachment options. (line 60) -* org-attach-auto-tag: Attachment options. (line 64) -* org-attach-commands: Attachment options. (line 85) -* org-attach-dir-relative: Attachment options. (line 13) -* org-attach-expert: Attachment options. (line 88) -* org-attach-id-dir: Attachment options. (line 9) -* org-attach-id-to-path-function-list: Attachment options. (line 68) -* org-attach-method: Attachment defaults and dispatcher. - (line 25) -* org-attach-method <1>: Attachment options. (line 49) -* org-attach-preferred-new-method: Attachment options. (line 55) -* org-attach-store-link-p: Attachment options. (line 77) -* org-attach-use-inheritance: Attachment options. (line 18) -* org-babel-default-header-args: Using Header Arguments. - (line 19) -* org-babel-default-header-args <1>: Using Header Arguments. - (line 19) -* org-babel-inline-result-wrap: Evaluating Code Blocks. - (line 27) -* org-babel-load-languages: Languages. (line 10) -* org-babel-post-tangle-hook: Extracting Source Code. - (line 122) -* org-beamer-environments-default: Frames and Blocks in Beamer. - (line 25) -* org-beamer-environments-extra: Frames and Blocks in Beamer. - (line 25) -* org-beamer-frame-level: Frames and Blocks in Beamer. - (line 10) -* org-beamer-theme: Beamer specific export settings. - (line 11) -* org-calc-default-modes: Formula syntax for Calc. - (line 17) -* org-capture-bookmark: Using capture. (line 48) -* org-capture-last-stored: Using capture. (line 48) -* org-capture-templates: Capture templates. (line 11) -* org-capture-templates-contexts: Templates in contexts. - (line 6) -* org-capture-use-agenda-date: Agenda Commands. (line 345) -* org-catch-invisible-edits: Catching invisible edits. - (line 6) -* org-clock-auto-clockout-timer: Resolving idle time. (line 91) -* org-clock-continuously: Clocking commands. (line 7) -* org-clock-continuously <1>: Clocking commands. (line 44) -* org-clock-continuously <2>: Resolving idle time. (line 78) -* org-clock-display-default-range: The clock table. (line 80) -* org-clock-idle-time: Resolving idle time. (line 14) -* org-clock-in-prepare-hook: Clocking commands. (line 21) -* org-clock-into-drawer: Clocking commands. (line 7) -* org-clock-mode-line-total: Clocking commands. (line 21) -* org-clock-persist: Clocking Work Time. (line 19) -* org-clock-report-include-clocking-task: Agenda Commands. (line 154) -* org-clock-x11idle-program-name: Resolving idle time. (line 14) -* org-clocktable-defaults: The clock table. (line 39) -* org-closed-keep-when-no-todo: Closing items. (line 11) -* org-coderef-label-format: Literal Examples. (line 88) -* org-columns: Using column view. (line 10) -* org-columns-default-format: Using column view. (line 10) -* org-columns-default-format <1>: Effort Estimates. (line 35) -* org-columns-default-format <2>: Agenda Commands. (line 197) -* org-columns-default-format <3>: Agenda Column View. (line 19) -* org-columns-default-format-for-agenda: Agenda Column View. (line 19) -* org-columns-skip-archived-trees: Internal archiving. (line 33) -* org-columns-summary-types: Column attributes. (line 51) -* org-complete-tags-always-offer-all-agenda-tags: Setting Tags. - (line 22) -* org-confirm-babel-evaluate: Code Evaluation Security. - (line 25) -* org-create-file-search-functions: Custom Searches. (line 12) -* org-crypt-tag-matcher: Org Crypt. (line 11) -* org-ctrl-k-protect-subtree: Headlines. (line 6) -* org-cycle-emulate-tab: Global and local cycling. - (line 16) -* org-cycle-global-at-bob: Global and local cycling. - (line 31) -* org-cycle-include-plain-lists: Plain Lists. (line 70) -* org-cycle-open-archived-trees: Internal archiving. (line 13) -* org-cycle-separator-lines: Headlines. (line 29) -* org-deadline-warning-days: Deadlines and Scheduling. - (line 14) -* org-deadline-warning-days <1>: Inserting deadline/schedule. - (line 26) -* org-default-notes-file: Setting up capture. (line 8) -* org-default-notes-file <1>: Template elements. (line 50) -* org-directory: Template elements. (line 50) -* org-display-custom-times: Custom time format. (line 6) -* org-disputed-keys: Conflicts. (line 27) -* org-done, face: Faces for TODO keywords. - (line 6) -* org-edit-src-auto-save-idle-delay: Editing Source Code. (line 11) -* org-effort-property: Effort Estimates. (line 6) -* org-enforce-todo-dependencies: TODO dependencies. (line 6) -* org-enforce-todo-dependencies <1>: TODO dependencies. (line 53) -* org-entities-user: Special Symbols. (line 16) -* org-execute-file-search-functions: Custom Searches. (line 12) -* org-export-allow-bind-keywords: Export Settings. (line 210) -* org-export-async-init-file: The Export Dispatcher. - (line 42) -* org-export-backends: Exporting. (line 33) -* org-export-before-parsing-hook: Advanced Export Configuration. - (line 9) -* org-export-before-processing-hook: Advanced Export Configuration. - (line 9) -* org-export-creator-string: HTML preamble and postamble. - (line 6) -* org-export-date-timestamp-format: Export Settings. (line 32) -* org-export-default-language: Export Settings. (line 38) -* org-export-dispatch-use-expert-ui: The Export Dispatcher. - (line 10) -* org-export-exclude-tags: Export Settings. (line 52) -* org-export-global-macros: Macro Replacement. (line 6) -* org-export-headline-levels: Export Settings. (line 141) -* org-export-html-table-tag: Tables in HTML export. - (line 6) -* org-export-html-tag-class-prefix: CSS support. (line 6) -* org-export-html-todo-kwd-class-prefix: CSS support. (line 6) -* org-export-html-use-infojs: JavaScript support. (line 70) -* org-export-in-background: The Export Dispatcher. - (line 39) -* org-export-initial-scope: The Export Dispatcher. - (line 60) -* org-export-odt-convert-capabilities: Advanced topics in ODT export. - (line 22) -* org-export-odt-convert-process: Advanced topics in ODT export. - (line 28) -* org-export-odt-convert-processes: Advanced topics in ODT export. - (line 17) -* org-export-odt-preferred-output-format: ODT export commands. - (line 25) -* org-export-odt-schema-dir: Advanced topics in ODT export. - (line 269) -* org-export-preserve-breaks: Export Settings. (line 93) -* org-export-select-tags: Export Settings. (line 44) -* org-export-time-stamp-file: Export Settings. (line 187) -* org-export-time-stamp-file <1>: HTML preamble and postamble. - (line 6) -* org-export-use-babel: Exporting Code Blocks. - (line 34) -* org-export-with-archived-trees: Internal archiving. (line 29) -* org-export-with-archived-trees <1>: Export Settings. (line 102) -* org-export-with-author: Export Settings. (line 107) -* org-export-with-broken-links: Export Settings. (line 111) -* org-export-with-clocks: Export Settings. (line 116) -* org-export-with-creator: Export Settings. (line 119) -* org-export-with-date: Export Settings. (line 127) -* org-export-with-drawers: Export Settings. (line 123) -* org-export-with-email: Export Settings. (line 134) -* org-export-with-emphasize: Export Settings. (line 79) -* org-export-with-entities: Export Settings. (line 131) -* org-export-with-fixed-width: Export Settings. (line 86) -* org-export-with-footnotes: Export Settings. (line 138) -* org-export-with-inlinetasks: Export Settings. (line 146) -* org-export-with-latex: LaTeX fragments. (line 38) -* org-export-with-latex <1>: Export Settings. (line 183) -* org-export-with-planning: Export Settings. (line 157) -* org-export-with-priority: Export Settings. (line 163) -* org-export-with-properties: Export Settings. (line 166) -* org-export-with-section-numbers: Export Settings. (line 149) -* org-export-with-smart-quotes: Export Settings. (line 73) -* org-export-with-special-strings: Export Settings. (line 82) -* org-export-with-statistics-cookies: Export Settings. (line 170) -* org-export-with-sub-superscripts: Export Settings. (line 97) -* org-export-with-tables: Export Settings. (line 202) -* org-export-with-tags: Export Settings. (line 174) -* org-export-with-tasks: Export Settings. (line 178) -* org-export-with-timestamps: Export Settings. (line 89) -* org-export-with-title: Export Settings. (line 191) -* org-export-with-toc: Export Settings. (line 194) -* org-export-with-toc <1>: Table of Contents. (line 6) -* org-export-with-todo-keywords: Export Settings. (line 198) -* org-expot-creator-string: Export Settings. (line 28) -* org-faces-easy-properties: Faces for TODO keywords. - (line 17) -* org-fast-tag-selection-include-todo: Fast access to TODO states. - (line 16) -* org-fast-tag-selection-single-key: Setting Tags. (line 142) -* org-file-apps: Handling Links. (line 108) -* org-file-apps <1>: Attachment defaults and dispatcher. - (line 46) -* org-fontify-emphasized-text: Emphasis and Monospace. - (line 11) -* org-footnote-auto-adjust: Creating Footnotes. (line 60) -* org-footnote-auto-adjust <1>: In-buffer Settings. (line 157) -* org-footnote-auto-label: Creating Footnotes. (line 32) -* org-footnote-auto-label <1>: In-buffer Settings. (line 157) -* org-footnote-define-inline: Creating Footnotes. (line 45) -* org-footnote-define-inline <1>: In-buffer Settings. (line 157) -* org-footnote-section: Headlines. (line 18) -* org-footnote-section <1>: Creating Footnotes. (line 45) -* org-format-latex-header: LaTeX fragments. (line 6) -* org-format-latex-header <1>: Previewing LaTeX fragments. - (line 12) -* org-format-latex-options: Previewing LaTeX fragments. - (line 12) -* org-global-properties: Property Syntax. (line 80) -* org-global-properties <1>: Effort Estimates. (line 35) -* org-goto-auto-isearch: Motion. (line 24) -* org-goto-interface: Motion. (line 41) -* org-group-tags: Tag Hierarchy. (line 87) -* org-habit-following-days: Tracking your habits. - (line 91) -* org-habit-graph-column: Tracking your habits. - (line 82) -* org-habit-preceding-days: Tracking your habits. - (line 87) -* org-habit-show-habits-only-for-today: Tracking your habits. - (line 94) -* org-hide, face: Hard indentation. (line 21) -* org-hide-block-startup: Blocks. (line 6) -* org-hide-block-startup <1>: In-buffer Settings. (line 170) -* org-hide-leading-stars: Hard indentation. (line 21) -* org-hide-leading-stars <1>: In-buffer Settings. (line 133) -* org-hide-macro-markers: Macro Replacement. (line 88) -* org-hierarchical-checkbox-statistics: Checkboxes. (line 29) -* org-hierarchical-todo-statistics: Breaking Down Tasks. (line 25) -* org-html-container-element: HTML specific export settings. - (line 22) -* org-html-doctype: HTML specific export settings. - (line 19) -* org-html-doctype <1>: HTML doctypes. (line 8) -* org-html-doctype-alist: HTML doctypes. (line 8) -* org-html-head: HTML specific export settings. - (line 38) -* org-html-head <1>: CSS support. (line 44) -* org-html-head <2>: Bare HTML. (line 9) -* org-html-head-extra: HTML specific export settings. - (line 42) -* org-html-head-extra <1>: CSS support. (line 44) -* org-html-head-extra <2>: Bare HTML. (line 9) -* org-html-head-include-default-style: CSS support. (line 52) -* org-html-head-include-default-style <1>: Bare HTML. (line 9) -* org-html-head-include-scripts: Bare HTML. (line 9) -* org-html-html5-elements: HTML doctypes. (line 60) -* org-html-html5-fancy: HTML doctypes. (line 25) -* org-html-inline-images: Images in HTML export. - (line 9) -* org-html-link-home: HTML specific export settings. - (line 26) -* org-html-link-org-files-as-html: Links in HTML export. - (line 12) -* org-html-link-up: HTML specific export settings. - (line 29) -* org-html-mathjax-options: HTML specific export settings. - (line 33) -* org-html-mathjax-options~: Math formatting in HTML export. - (line 6) -* org-html-mathjax-template: Math formatting in HTML export. - (line 20) -* org-html-postamble: HTML preamble and postamble. - (line 6) -* org-html-postamble <1>: Bare HTML. (line 9) -* org-html-postamble-format: HTML preamble and postamble. - (line 6) -* org-html-preamble: HTML preamble and postamble. - (line 6) -* org-html-preamble <1>: Bare HTML. (line 9) -* org-html-preamble-format: HTML preamble and postamble. - (line 6) -* org-html-self-link-headlines: Headlines in HTML export. - (line 10) -* org-html-style-default: CSS support. (line 44) -* org-html-table-align-individual-fields: Tables in HTML export. - (line 20) -* org-html-table-caption-above: Tables in HTML export. - (line 24) -* org-html-table-data-tags: Tables in HTML export. - (line 27) -* org-html-table-default-attributes: Tables in HTML export. - (line 30) -* org-html-table-header-tags: Tables in HTML export. - (line 33) -* org-html-table-row-tags: Tables in HTML export. - (line 36) -* org-html-table-use-header-tags-for-first-column: Tables in HTML export. - (line 39) -* org-html-use-infojs: Bare HTML. (line 9) -* org-html-validation-link: HTML preamble and postamble. - (line 6) -* org-icalendar-alarm-time: iCalendar Export. (line 20) -* org-icalendar-categories: iCalendar Export. (line 20) -* org-icalendar-combined-agenda-file: iCalendar Export. (line 47) -* org-icalendar-include-body: iCalendar Export. (line 57) -* org-icalendar-include-todo: iCalendar Export. (line 11) -* org-icalendar-store-UID: iCalendar Export. (line 26) -* org-icalendar-use-deadline: iCalendar Export. (line 11) -* org-icalendar-use-scheduled: iCalendar Export. (line 11) -* org-id-link-to-org-use-id: Handling Links. (line 21) -* org-imenu-depth: Cooperation. (line 37) -* org-indent-indentation-per-level: Org Indent Mode. (line 11) -* org-indent-mode-turns-off-org-adapt-indentation: Org Indent Mode. - (line 15) -* org-indent-mode-turns-on-hiding-stars: Org Indent Mode. (line 15) -* org-infojs-options: JavaScript support. (line 70) -* org-insert-mode-line-in-empty-file: Activation. (line 30) -* org-irc-links-to-logs: Handling Links. (line 47) -* org-latex-bibtex-compiler: LaTeX/PDF export commands. - (line 25) -* org-latex-classes: LaTeX specific export settings. - (line 32) -* org-latex-classes <1>: LaTeX specific export settings. - (line 49) -* org-latex-classes <2>: LaTeX header and sectioning. - (line 13) -* org-latex-compiler: LaTeX/PDF export commands. - (line 25) -* org-latex-compiler <1>: LaTeX specific export settings. - (line 44) -* org-latex-default-class: LaTeX specific export settings. - (line 32) -* org-latex-default-class <1>: LaTeX header and sectioning. - (line 13) -* org-latex-default-packages-alist: LaTeX/PDF export commands. - (line 25) -* org-latex-default-packages-alist <1>: LaTeX header and sectioning. - (line 13) -* org-latex-default-table-environment: Tables in LaTeX export. - (line 23) -* org-latex-default-table-mode: Tables in LaTeX export. - (line 12) -* org-latex-hyperref-template: LaTeX specific export settings. - (line 11) -* org-latex-hyperref-template <1>: LaTeX specific export settings. - (line 54) -* org-latex-images-centered: Images in LaTeX export. - (line 60) -* org-latex-listings: Literal Examples. (line 31) -* org-latex-listings-options: Source blocks in LaTeX export. - (line 25) -* org-latex-minted-options: Source blocks in LaTeX export. - (line 25) -* org-latex-packages-alist: LaTeX specific export settings. - (line 20) -* org-latex-packages-alist <1>: LaTeX header and sectioning. - (line 13) -* org-latex-subtitle-format: LaTeX specific export settings. - (line 63) -* org-latex-subtitle-separate: LaTeX specific export settings. - (line 63) -* org-latex-tables-booktabs: Tables in LaTeX export. - (line 65) -* org-latex-tables-centered: Tables in LaTeX export. - (line 65) -* org-latex-title-command: LaTeX specific export settings. - (line 11) -* org-latex-title-command <1>: LaTeX specific export settings. - (line 54) -* org-latex-to-mathml-convert-command: LaTeX math snippets. (line 20) -* org-latex-to-mathml-jar-file: LaTeX math snippets. (line 20) -* org-link-abbrev-alist: Link Abbreviations. (line 12) -* org-link-abbrev-alist <1>: In-buffer Settings. (line 38) -* org-link-elisp-confirm-function: Code Evaluation Security. - (line 52) -* org-link-email-description-format: Handling Links. (line 33) -* org-link-frame-setup: Handling Links. (line 123) -* org-link-from-user-regexp: Template expansion. (line 108) -* org-link-keep-stored-after-insertion: Handling Links. (line 71) -* org-link-parameters: Adding Hyperlink Types. - (line 74) -* org-link-search-must-match-exact-headline: Internal Links. (line 31) -* org-link-shell-confirm-function: Code Evaluation Security. - (line 49) -* org-link-use-indirect-buffer-for-internals: Handling Links. (line 137) -* org-list-automatic-rules: Plain Lists. (line 63) -* org-list-automatic-rules <1>: Checkboxes. (line 6) -* org-list-demote-modify-bullet: Plain Lists. (line 57) -* org-list-indent-offset: Plain Lists. (line 57) -* org-list-use-circular-motion: Plain Lists. (line 95) -* org-log-done: Tracking TODO state changes. - (line 25) -* org-log-done <1>: Agenda Commands. (line 131) -* org-log-done <2>: In-buffer Settings. (line 111) -* org-log-into-drawer: Tracking TODO state changes. - (line 6) -* org-log-into-drawer <1>: Agenda Commands. (line 295) -* org-log-note-clock-out: Clocking commands. (line 36) -* org-log-note-clock-out <1>: In-buffer Settings. (line 111) -* org-log-redeadline: Inserting deadline/schedule. - (line 10) -* org-log-refile: Refile and Copy. (line 13) -* org-log-repeat: Repeated tasks. (line 40) -* org-log-repeat <1>: In-buffer Settings. (line 111) -* org-log-reschedule: Inserting deadline/schedule. - (line 18) -* org-log-states-order-reversed: Tracking TODO state changes. - (line 6) -* org-loop-over-headlines-in-active-region: Execute commands in the active region. - (line 6) -* org-M-RET-may-split-line: Structure Editing. (line 7) -* org-M-RET-may-split-line <1>: Plain Lists. (line 83) -* org-md-headline-style: Markdown Export. (line 29) -* org-mobile-directory: Setting up the staging area. - (line 6) -* org-mobile-encryption: Setting up the staging area. - (line 19) -* org-mobile-files: Pushing to the mobile application. - (line 6) -* org-mobile-inbox-for-pull: Pulling from the mobile application. - (line 12) -* org-num-face: Dynamic Headline Numbering. - (line 19) -* org-num-format-function: Dynamic Headline Numbering. - (line 19) -* org-num-max-level: Dynamic Headline Numbering. - (line 10) -* org-num-skip-commented: Dynamic Headline Numbering. - (line 10) -* org-num-skip-footnotes: Dynamic Headline Numbering. - (line 16) -* org-num-skip-tags: Dynamic Headline Numbering. - (line 10) -* org-num-skip-unnumbered: Dynamic Headline Numbering. - (line 10) -* org-odd-levels-only: Matching tags and properties. - (line 65) -* org-odd-levels-only <1>: Hard indentation. (line 29) -* org-odd-levels-only <2>: In-buffer Settings. (line 133) -* org-odd-levels-only <3>: Special Agenda Views. - (line 41) -* org-odt-category-map-alist: Labels and captions in ODT export. - (line 21) -* org-odt-convert-process: Extending ODT export. - (line 12) -* org-odt-create-custom-styles-for-srcblocks: Literal examples in ODT export. - (line 16) -* org-odt-fontify-srcblocks: Literal examples in ODT export. - (line 13) -* org-odt-pixels-per-inch: Images in ODT export. - (line 34) -* org-odt-preferred-output-format: ODT export commands. (line 9) -* org-odt-preferred-output-format <1>: Extending ODT export. - (line 21) -* org-odt-styles-file: ODT specific export settings. - (line 22) -* org-odt-styles-file <1>: Applying custom styles. - (line 25) -* org-odt-table-styles: Advanced topics in ODT export. - (line 158) -* org-odt-table-styles <1>: Advanced topics in ODT export. - (line 226) -* org-outline-path-complete-in-steps: Refile and Copy. (line 13) -* org-plain-list-ordered-item-terminator: Plain Lists. (line 15) -* org-plain-list-ordered-item-terminator <1>: Plain Lists. (line 131) -* org-popup-calendar-for-date-prompt: The date/time prompt. - (line 78) -* org-pretty-entities: Subscripts and Superscripts. - (line 29) -* org-pretty-entities <1>: In-buffer Settings. (line 176) -* org-pretty-entities-include-sub-superscripts: Subscripts and Superscripts. - (line 29) -* org-preview-latex-default-process: Previewing LaTeX fragments. - (line 6) -* org-priority-default: Priorities. (line 46) -* org-priority-default <1>: In-buffer Settings. (line 43) -* org-priority-faces: Priorities. (line 13) -* org-priority-highest: Priorities. (line 46) -* org-priority-highest <1>: In-buffer Settings. (line 43) -* org-priority-lowest: Priorities. (line 46) -* org-priority-lowest <1>: In-buffer Settings. (line 43) -* org-priority-start-cycle-with-default: Priorities. (line 41) -* org-property-allowed-value-functions: Using the Property API. - (line 63) -* org-protocol-default-template-key: The capture protocol. - (line 30) -* org-protocol-project-alist: The open-source protocol. - (line 13) -* org-publish-project-alist: Project alist. (line 6) -* org-publish-project-alist <1>: Publishing options. (line 12) -* org-publish-use-timestamps-flag: Triggering Publication. - (line 21) -* org-put-time-stamp-overlays: In-buffer Settings. (line 145) -* org-read-date-display-live: The date/time prompt. - (line 98) -* org-read-date-force-compatible-dates: The date/time prompt. - (line 62) -* org-read-date-prefer-future: The date/time prompt. - (line 6) -* org-refile-allow-creating-parent-nodes: Refile and Copy. (line 13) -* org-refile-keep: Refile and Copy. (line 41) -* org-refile-targets: Refile and Copy. (line 13) -* org-refile-use-cache: Refile and Copy. (line 46) -* org-refile-use-outline-path: Refile and Copy. (line 13) -* org-remove-highlights-with-change: Sparse Trees. (line 20) -* org-remove-highlights-with-change <1>: Clocking commands. (line 84) -* org-replace-disputed-keys: Conflicts. (line 17) -* org-return-follows-link: Handling Links. (line 129) -* org-reverse-note-order: Refile and Copy. (line 13) -* org-scheduled-delay-days: Deadlines and Scheduling. - (line 42) -* org-show-context-detail: Sparse Trees. (line 6) -* org-sort-agenda-noeffort-is-high: Filtering/limiting agenda items. - (line 56) -* org-sparse-tree-open-archived-trees: Internal archiving. (line 19) -* org-special-ctrl-a/e: Headlines. (line 6) -* org-special-ctrl-k: Headlines. (line 6) -* org-speed-commands: Speed Keys. (line 18) -* org-src-ask-before-returning-to-edit-buffer: Editing Source Code. - (line 40) -* org-src-block-faces: Editing Source Code. (line 43) -* org-src-fontify-natively: Editing Source Code. (line 43) -* org-src-lang-modes: Editing Source Code. (line 22) -* org-src-preserve-indentation: Editing Source Code. (line 32) -* org-src-window-setup: Editing Source Code. (line 28) -* org-startup-align-all-tables: Column Width and Alignment. - (line 19) -* org-startup-align-all-tables <1>: In-buffer Settings. (line 93) -* org-startup-folded: Initial visibility. (line 6) -* org-startup-folded <1>: In-buffer Settings. (line 67) -* org-startup-folded <2>: Speeding Up Your Agendas. - (line 19) -* org-startup-indented: Org Indent Mode. (line 22) -* org-startup-indented <1>: In-buffer Settings. (line 81) -* org-startup-numerated: Dynamic Headline Numbering. - (line 22) -* org-startup-numerated <1>: In-buffer Settings. (line 87) -* org-startup-shrink-all-tables: Column Width and Alignment. - (line 64) -* org-startup-shrink-all-tables <1>: In-buffer Settings. (line 100) -* org-startup-with-inline-images: Images. (line 24) -* org-startup-with-inline-images <1>: In-buffer Settings. (line 104) -* org-startup-with-latex-preview: Previewing LaTeX fragments. - (line 28) -* org-store-link-props: Template expansion. (line 106) -* org-structure-template-alist: Structure Templates. (line 17) -* org-stuck-projects: Stuck projects. (line 17) -* org-support-shift-select: Plain Lists. (line 95) -* org-support-shift-select <1>: Plain Lists. (line 154) -* org-support-shift-select <2>: Conflicts. (line 6) -* org-table-automatic-realign: Column Width and Alignment. - (line 10) -* org-table-copy-increment: Built-in Table Editor. - (line 186) -* org-table-current-column: References. (line 90) -* org-table-current-dline: References. (line 90) -* org-table-duration-custom-format: Durations and time values. - (line 6) -* org-table-export-default-format: Built-in Table Editor. - (line 226) -* org-table-formula: In-buffer Settings. (line 28) -* org-table-formula-constants: References. (line 114) -* org-table-formula-constants <1>: In-buffer Settings. (line 28) -* org-table-formula-constants <2>: Cooperation. (line 14) -* org-table-header-line-p: Built-in Table Editor. - (line 237) -* org-table-use-standard-references: Editing and debugging formulas. - (line 6) -* org-tag-alist: Setting Tags. (line 22) -* org-tag-alist <1>: In-buffer Settings. (line 183) -* org-tag-faces: Tags. (line 10) -* org-tag-persistent-alist: Setting Tags. (line 37) -* org-tags-column: Setting Tags. (line 11) -* org-tags-exclude-from-inheritance: Tag Inheritance. (line 22) -* org-tags-match-list-sublevels: Tag Inheritance. (line 26) -* org-tags-match-list-sublevels <1>: Tag Searches. (line 19) -* org-tags-match-list-sublevels <2>: Property Searches. (line 18) -* org-tags-match-list-sublevels <3>: Matching tags and properties. - (line 21) -* org-tempo-keywords-alist: Structure Templates. (line 21) -* org-texinfo-classes: Texinfo file header. (line 19) -* org-texinfo-classes <1>: Headings and sectioning structure. - (line 6) -* org-texinfo-coding-system: Texinfo file header. (line 11) -* org-texinfo-default-class: Texinfo specific export settings. - (line 20) -* org-texinfo-default-class <1>: Headings and sectioning structure. - (line 6) -* org-texinfo-info-process: Texinfo export commands. - (line 11) -* org-texinfo-table-default-markup: Plain lists in Texinfo export. - (line 12) -* org-time-stamp-custom-formats: Custom time format. (line 6) -* org-time-stamp-overlay-formats: In-buffer Settings. (line 145) -* org-time-stamp-rounding-minutes: Creating Timestamps. (line 16) -* org-timer-default-timer: Timers. (line 23) -* org-todo, face: Faces for TODO keywords. - (line 6) -* org-todo-keyword-faces: Faces for TODO keywords. - (line 6) -* org-todo-keywords: TODO Basics. (line 35) -* org-todo-keywords <1>: TODO Extensions. (line 6) -* org-todo-keywords <2>: Global TODO list. (line 18) -* org-todo-keywords <3>: In-buffer Settings. (line 190) -* org-todo-repeat-to-state: Repeated tasks. (line 22) -* org-todo-state-tags-triggers: TODO Basics. (line 56) -* org-track-ordered-property-with-tag: TODO dependencies. (line 38) -* org-track-ordered-property-with-tag <1>: Checkboxes. (line 90) -* org-treat-insert-todo-heading-as-state-change: Structure Editing. - (line 29) -* org-treat-S-cursor-todo-selection-as-state-change: TODO Basics. - (line 28) -* org-use-property-inheritance: Property Inheritance. - (line 6) -* org-use-property-inheritance <1>: Using Header Arguments. - (line 56) -* org-use-property-inheritance <2>: Using the Property API. - (line 19) -* org-use-speed-commands: Speed Keys. (line 13) -* org-use-sub-superscripts: Subscripts and Superscripts. - (line 13) -* org-use-tag-inheritance: Tag Inheritance. (line 22) -* org-yank-adjusted-subtrees: Structure Editing. (line 84) -* org-yank-folded-subtrees: Structure Editing. (line 84) -* parse-time-months: The date/time prompt. - (line 58) -* parse-time-weekdays: The date/time prompt. - (line 58) -* user-full-name: Export Settings. (line 25) -* user-mail-address: Export Settings. (line 35) - - - -Tag Table: -Node: Top884 -Node: Introduction22812 -Node: Summary23274 -Node: Installation25991 -Ref: Using Emacs packaging system26533 -Ref: Using Org's git repository27041 -Ref: Installing Org's contributed packages27951 -Node: Activation28287 -Ref: Activation-Footnote-129910 -Node: Feedback30038 -Ref: How to create a useful backtrace32724 -Ref: Feedback-Footnote-133876 -Node: Conventions34002 -Ref: TODO keywords tags properties etc34173 -Ref: Key bindings and commands35066 -Node: Document Structure35696 -Node: Headlines36868 -Ref: Headlines-Footnote-138166 -Node: Visibility Cycling38445 -Node: Global and local cycling38835 -Ref: Global and local cycling-Footnote-141552 -Ref: Global and local cycling-Footnote-241614 -Node: Initial visibility41918 -Ref: Initial visibility-Footnote-143102 -Node: Catching invisible edits43295 -Node: Motion43771 -Node: Structure Editing45235 -Node: Sparse Trees51695 -Ref: Sparse Trees-Footnote-154292 -Ref: Sparse Trees-Footnote-254407 -Node: Plain Lists54483 -Ref: Plain Lists-Footnote-162008 -Ref: Plain Lists-Footnote-262372 -Ref: Plain Lists-Footnote-362472 -Ref: Plain Lists-Footnote-462729 -Ref: Plain Lists-Footnote-562906 -Ref: Plain Lists-Footnote-663010 -Ref: Plain Lists-Footnote-763116 -Node: Drawers63186 -Ref: Drawers-Footnote-164856 -Node: Blocks64968 -Node: Tables65561 -Node: Built-in Table Editor66244 -Ref: Creation and conversion67978 -Ref: Re-aligning and field motion68916 -Ref: Column and row editing69829 -Ref: Regions72259 -Ref: Calculations73658 -Ref: Miscellaneous (1)74471 -Ref: Built-in Table Editor-Footnote-176948 -Node: Column Width and Alignment77056 -Node: Column Groups80393 -Node: Orgtbl Mode81960 -Node: The Spreadsheet82775 -Node: References84249 -Ref: Field references84708 -Ref: Range references87147 -Ref: Field coordinates in formulas88406 -Ref: Named references89391 -Ref: Remote references90362 -Ref: References-Footnote-191284 -Ref: References-Footnote-291512 -Ref: References-Footnote-391615 -Node: Formula syntax for Calc91940 -Ref: Formula syntax for Calc-Footnote-197801 -Node: Formula syntax for Lisp98140 -Node: Durations and time values100373 -Node: Field and range formulas101760 -Node: Column formulas104229 -Node: Lookup functions106341 -Node: Editing and debugging formulas108310 -Ref: Using multiple TBLFM lines112827 -Ref: Debugging formulas113670 -Node: Updating the table114094 -Node: Advanced features115466 -Ref: Advanced features-Footnote-1119917 -Node: Org Plot120025 -Ref: Graphical plots using Gnuplot120226 -Ref: Plot options122749 -Ref: ASCII bar plots125541 -Node: Hyperlinks126791 -Node: Link Format127655 -Ref: Link Format-Footnote-1129718 -Ref: Link Format-Footnote-2129950 -Node: Internal Links130082 -Ref: Internal Links-Footnote-1132644 -Ref: Internal Links-Footnote-2132884 -Node: Radio Targets133025 -Node: External Links133742 -Ref: External Links-Footnote-1139226 -Node: Handling Links139650 -Ref: Handling Links-Footnote-1147413 -Ref: Handling Links-Footnote-2147574 -Ref: Handling Links-Footnote-3147764 -Ref: Handling Links-Footnote-4148060 -Ref: Handling Links-Footnote-5148322 -Ref: Handling Links-Footnote-6148444 -Node: Using Links Outside Org148519 -Node: Link Abbreviations148994 -Node: Search Options151830 -Ref: Search Options-Footnote-1153968 -Node: Custom Searches154049 -Node: TODO Items155083 -Ref: TODO Items-Footnote-1156208 -Node: TODO Basics156322 -Node: TODO Extensions158957 -Node: Workflow states160010 -Ref: Workflow states-Footnote-1161409 -Node: TODO types161525 -Ref: TODO types-Footnote-1163344 -Node: Multiple sets in one file163416 -Node: Fast access to TODO states165361 -Ref: Fast access to TODO states-Footnote-1166244 -Ref: Fast access to TODO states-Footnote-2166351 -Node: Per-file keywords166653 -Ref: Per-file keywords-Footnote-1168123 -Node: Faces for TODO keywords168327 -Node: TODO dependencies169400 -Node: Progress Logging171891 -Node: Closing items173028 -Ref: Closing items-Footnote-1174028 -Ref: Closing items-Footnote-2174102 -Node: Tracking TODO state changes174180 -Ref: Tracking TODO state changes-Footnote-1177315 -Ref: Tracking TODO state changes-Footnote-2177377 -Ref: Tracking TODO state changes-Footnote-3177535 -Node: Tracking your habits177813 -Node: Priorities182234 -Ref: Priorities-Footnote-1184746 -Node: Breaking Down Tasks184819 -Ref: Breaking Down Tasks-Footnote-1186861 -Node: Checkboxes186968 -Ref: Checkboxes-Footnote-1192111 -Ref: Checkboxes-Footnote-2192239 -Ref: Checkboxes-Footnote-3192419 -Node: Tags192533 -Node: Tag Inheritance193626 -Ref: Tag Inheritance-Footnote-1195498 -Ref: Tag Inheritance-Footnote-2195602 -Node: Setting Tags195732 -Ref: Setting Tags-Footnote-1202303 -Ref: Setting Tags-Footnote-2202481 -Node: Tag Hierarchy202559 -Node: Tag Searches206159 -Node: Properties and Columns207470 -Node: Property Syntax208858 -Node: Special Properties213464 -Node: Property Searches215154 -Node: Property Inheritance216629 -Node: Column View218501 -Node: Defining columns219752 -Node: Scope of column definitions220137 -Node: Column attributes221196 -Ref: Column attributes-Footnote-1225607 -Ref: Column attributes-Footnote-2225738 -Ref: Column attributes-Footnote-3225936 -Node: Using column view226075 -Ref: Turning column view on or off226241 -Ref: Editing values227282 -Ref: Modifying column view on-the-fly228685 -Node: Capturing column view229057 -Ref: Capturing column view-Footnote-1232785 -Node: Dates and Times232922 -Node: Timestamps233841 -Ref: Timestamps-Footnote-1236197 -Ref: Timestamps-Footnote-2236493 -Node: Creating Timestamps237242 -Node: The date/time prompt240256 -Ref: The date/time prompt-Footnote-1245217 -Ref: The date/time prompt-Footnote-2245388 -Ref: The date/time prompt-Footnote-3245499 -Ref: The date/time prompt-Footnote-4245754 -Node: Custom time format245852 -Node: Deadlines and Scheduling247621 -Ref: Deadlines and Scheduling-Footnote-1251191 -Node: Inserting deadline/schedule251354 -Ref: Inserting deadline/schedule-Footnote-1253346 -Ref: Inserting deadline/schedule-Footnote-2253507 -Ref: Inserting deadline/schedule-Footnote-3253633 -Node: Repeated tasks253759 -Ref: Repeated tasks-Footnote-1258394 -Ref: Repeated tasks-Footnote-2258477 -Ref: Repeated tasks-Footnote-3258760 -Node: Clocking Work Time258982 -Ref: Clocking Work Time-Footnote-1260187 -Ref: Clocking Work Time-Footnote-2260340 -Node: Clocking commands260482 -Ref: Clocking commands-Footnote-1265587 -Ref: Clocking commands-Footnote-2265702 -Ref: Clocking commands-Footnote-3265784 -Ref: Clocking commands-Footnote-4265847 -Node: The clock table265930 -Ref: The clock table-Footnote-1274013 -Ref: The clock table-Footnote-2274122 -Ref: The clock table-Footnote-3274220 -Node: Resolving idle time274346 -Ref: Resolving idle time (1)274542 -Ref: Continuous clocking277739 -Ref: Clocking out automatically after some idle time278245 -Ref: Resolving idle time-Footnote-1278877 -Node: Effort Estimates279325 -Ref: Effort Estimates-Footnote-1282282 -Node: Timers282393 -Node: Refiling and Archiving284612 -Node: Refile and Copy285175 -Ref: Refile and Copy-Footnote-1288003 -Node: Archiving288117 -Node: Moving subtrees288830 -Node: Internal archiving290956 -Node: Capture and Attachments293685 -Node: Capture294490 -Node: Setting up capture295014 -Node: Using capture295377 -Node: Capture templates297775 -Node: Template elements299814 -Ref: Template elements-Footnote-1307296 -Ref: Template elements-Footnote-2307629 -Ref: Template elements-Footnote-3307816 -Node: Template expansion307911 -Ref: Template expansion-Footnote-1311978 -Ref: Template expansion-Footnote-2312069 -Ref: Template expansion-Footnote-3312259 -Node: Templates in contexts312358 -Node: Attachments313203 -Node: Attachment defaults and dispatcher314233 -Ref: Attachment defaults and dispatcher-Footnote-1317583 -Node: Attachment options317734 -Node: Attachment links321753 -Node: Automatic version-control with Git322392 -Node: Attach from Dired322907 -Node: RSS Feeds324271 -Node: Agenda Views325722 -Node: Agenda Files328129 -Ref: Agenda Files-Footnote-1331040 -Ref: Agenda Files-Footnote-2331184 -Node: Agenda Dispatcher331382 -Ref: Agenda Dispatcher-Footnote-1334262 -Ref: Agenda Dispatcher-Footnote-2334360 -Node: Built-in Agenda Views334466 -Node: Weekly/daily agenda335063 -Ref: Calendar/Diary integration336403 -Ref: Anniversaries from BBDB338479 -Ref: Appointment reminders340270 -Ref: Weekly/daily agenda-Footnote-1340820 -Ref: Weekly/daily agenda-Footnote-2341064 -Node: Global TODO list341284 -Node: Matching tags and properties344134 -Node: Search view351243 -Node: Stuck projects352890 -Node: Presentation and Sorting355027 -Node: Categories356004 -Node: Time-of-day specifications356750 -Ref: Time-of-day specifications-Footnote-1358741 -Node: Sorting of agenda items358864 -Node: Filtering/limiting agenda items360482 -Ref: Filtering in the agenda361187 -Ref: Computed tag filtering365321 -Ref: Setting limits for the agenda366815 -Ref: Filtering/limiting agenda items-Footnote-1368364 -Node: Agenda Commands368916 -Ref: Motion (1)369649 -Ref: View/Go to Org file369852 -Ref: Change display371358 -Ref: Remote editing378868 -Ref: Bulk remote editing selected entries384221 -Ref: Calendar commands387316 -Ref: Quit and exit389197 -Ref: Agenda Commands-Footnote-1389559 -Ref: Agenda Commands-Footnote-2389635 -Ref: Agenda Commands-Footnote-3389739 -Node: Custom Agenda Views389826 -Node: Storing searches390478 -Ref: Storing searches-Footnote-1393430 -Ref: Storing searches-Footnote-2393547 -Node: Block agenda393794 -Node: Setting options395123 -Node: Exporting Agenda Views398737 -Ref: Exporting Agenda Views-Footnote-1403276 -Ref: Exporting Agenda Views-Footnote-2403464 -Ref: Exporting Agenda Views-Footnote-3403614 -Ref: Exporting Agenda Views-Footnote-4403801 -Node: Agenda Column View403883 -Node: Markup for Rich Contents407231 -Node: Paragraphs408529 -Node: Emphasis and Monospace409664 -Node: Subscripts and Superscripts410723 -Node: Special Symbols412341 -Ref: Special Symbols-Footnote-1414254 -Ref: Special Symbols-Footnote-2414419 -Node: Embedded LaTeX414516 -Ref: Embedded LaTeX-Footnote-1415365 -Node: LaTeX fragments415561 -Ref: LaTeX fragments-Footnote-1417718 -Node: Previewing LaTeX fragments417911 -Ref: Previewing LaTeX fragments-Footnote-1419394 -Node: CDLaTeX mode419642 -Ref: CDLaTeX mode-Footnote-1422373 -Node: Literal Examples422520 -Ref: Literal Examples-Footnote-1427631 -Ref: Literal Examples-Footnote-2427994 -Ref: Literal Examples-Footnote-3428172 -Ref: Literal Examples-Footnote-4428357 -Node: Images428455 -Ref: Images-Footnote-1429542 -Ref: Images-Footnote-2429665 -Node: Captions429826 -Node: Horizontal Rules430526 -Node: Creating Footnotes430782 -Ref: Creating Footnotes-Footnote-1433911 -Ref: Creating Footnotes-Footnote-2434017 -Node: Exporting434124 -Node: The Export Dispatcher436898 -Node: Export Settings439648 -Ref: Export Settings-Footnote-1447747 -Ref: Export Settings-Footnote-2447859 -Ref: Export Settings-Footnote-3447960 -Node: Table of Contents448158 -Ref: Table of Contents-Footnote-1450832 -Node: Include Files450999 -Ref: Include Files-Footnote-1453936 -Node: Macro Replacement454114 -Ref: Macro Replacement-Footnote-1457995 -Node: Comment Lines458212 -Ref: Comment Lines-Footnote-1459075 -Node: ASCII/Latin-1/UTF-8 export459179 -Ref: ASCII export commands460033 -Ref: ASCII specific export settings460566 -Ref: Header and sectioning structure461010 -Ref: Quoting ASCII text461284 -Ref: ASCII specific attributes461656 -Ref: ASCII special blocks461933 -Node: Beamer Export462280 -Node: Beamer export commands463030 -Node: Beamer specific export settings463735 -Node: Frames and Blocks in Beamer465640 -Ref: Frames and Blocks in Beamer-Footnote-1469012 -Node: Beamer specific syntax469171 -Node: Editing support471150 -Node: A Beamer example471621 -Node: HTML Export472875 -Node: HTML export commands473985 -Node: HTML specific export settings474527 -Node: HTML doctypes476746 -Node: HTML preamble and postamble478921 -Node: Quoting HTML tags480116 -Node: Headlines in HTML export480815 -Node: Links in HTML export481410 -Node: Tables in HTML export482880 -Node: Images in HTML export484337 -Node: Math formatting in HTML export485827 -Ref: Math formatting in HTML export-Footnote-1487368 -Ref: Math formatting in HTML export-Footnote-2487493 -Ref: Math formatting in HTML export-Footnote-3487754 -Node: Text areas in HTML export487926 -Node: CSS support489071 -Ref: CSS support-Footnote-1492723 -Node: JavaScript support492903 -Node: LaTeX Export496090 -Node: LaTeX/PDF export commands498010 -Ref: LaTeX/PDF export commands-Footnote-1499513 -Node: LaTeX specific export settings499715 -Node: LaTeX header and sectioning502947 -Node: Quoting LaTeX code505064 -Node: Tables in LaTeX export505860 -Node: Images in LaTeX export510278 -Node: Plain lists in LaTeX export512883 -Node: Source blocks in LaTeX export513903 -Ref: Source blocks in LaTeX export-Footnote-1515372 -Node: Example blocks in LaTeX export515530 -Node: Special blocks in LaTeX export516256 -Node: Horizontal rules in LaTeX export517519 -Node: Verse blocks in LaTeX export517956 -Node: Quote blocks in LaTeX export519970 -Node: Markdown Export521089 -Ref: Markdown export commands521556 -Ref: Header and sectioning structure (1)521993 -Node: OpenDocument Text Export522410 -Ref: OpenDocument Text Export-Footnote-1523516 -Node: Pre-requisites for ODT export523665 -Node: ODT export commands524043 -Node: ODT specific export settings525224 -Node: Extending ODT export526275 -Ref: Automatically exporting to other formats527086 -Ref: Converting between document formats527512 -Node: Applying custom styles528054 -Ref: Applying custom styles the easy way528586 -Ref: Using third-party styles and templates529544 -Node: Links in ODT export529841 -Node: Tables in ODT export530503 -Node: Images in ODT export532513 -Ref: Embedding images532717 -Ref: Embedding clickable images533034 -Ref: Sizing and scaling of embedded images533368 -Ref: Anchoring of images535052 -Node: Math formatting in ODT export535374 -Node: LaTeX math snippets535803 -Ref: LaTeX math snippets-Footnote-1538056 -Ref: LaTeX math snippets-Footnote-2538132 -Node: MathML and OpenDocument formula files538177 -Node: Labels and captions in ODT export538685 -Node: Literal examples in ODT export539961 -Node: Advanced topics in ODT export540802 -Ref: Configuring a document converter541112 -Ref: Working with OpenDocument style files542053 -Ref: x-orgodtstyles-xml542519 -Ref: x-orgodtcontenttemplate-xml542861 -Ref: x-overriding-factory-styles543505 -Ref: Creating one-off styles544749 -Ref: Customizing tables in ODT export546753 -Ref: Validating OpenDocument XML551613 -Ref: Advanced topics in ODT export-Footnote-1552410 -Ref: Advanced topics in ODT export-Footnote-2552514 -Ref: Advanced topics in ODT export-Footnote-3552607 -Node: Org Export552955 -Ref: Org export commands553311 -Node: Texinfo Export553617 -Node: Texinfo export commands554600 -Node: Texinfo specific export settings555225 -Node: Texinfo file header556378 -Node: Texinfo title and copyright page557361 -Node: Info directory file558725 -Node: Headings and sectioning structure559450 -Node: Indices561480 -Node: Quoting Texinfo code562509 -Node: Plain lists in Texinfo export563007 -Node: Tables in Texinfo export564733 -Node: Images in Texinfo export565229 -Node: Quotations in Texinfo export565867 -Node: Special blocks in Texinfo export566821 -Node: A Texinfo example567474 -Node: iCalendar Export569576 -Node: Other Built-in Back-ends573865 -Node: Advanced Export Configuration574497 -Ref: Export hooks574709 -Ref: Filters575647 -Ref: Defining filters for individual files578156 -Ref: Extending an existing back-end578962 -Node: Export in Foreign Buffers581202 -Node: Bare HTML582443 -Node: Publishing582985 -Node: Configuration583861 -Node: Project alist584643 -Node: Sources and destinations585785 -Node: Selecting files587103 -Node: Publishing action588058 -Ref: Publishing action-Footnote-1589891 -Node: Publishing options590054 -Ref: Generic properties590806 -Ref: ASCII specific properties592693 -Ref: Beamer specific properties594293 -Ref: HTML specific properties594858 -Ref: LaTeX specific properties599344 -Ref: Markdown specific properties602268 -Ref: ODT specific properties602506 -Ref: Texinfo specific properties603438 -Node: Publishing links604785 -Node: Site map606165 -Node: Generating an index609482 -Node: Uploading Files610274 -Node: Sample Configuration612057 -Node: Simple example612555 -Node: Complex example613271 -Node: Triggering Publication615320 -Node: Citation handling616346 -Node: Citations617215 -Node: Citation export processors618907 -Node: Working with Source Code621516 -Node: Features Overview623855 -Node: Structure of Code Blocks626614 -Node: Using Header Arguments629124 -Ref: System-wide header arguments629851 -Ref: Header arguments in Org mode properties630774 -Ref: Code block specific header arguments632602 -Ref: Header arguments in function calls634101 -Node: Environment of a Code Block634775 -Ref: Passing arguments634989 -Ref: Using sessions643178 -Ref: Choosing a working directory644577 -Ref: Inserting headers and footers646431 -Node: Evaluating Code Blocks646941 -Ref: How to evaluate source code647396 -Ref: Limit code block evaluation650298 -Ref: Cache results of evaluation651158 -Ref: Evaluating Code Blocks-Footnote-1653670 -Ref: Evaluating Code Blocks-Footnote-2653804 -Node: Results of Evaluation653962 -Ref: Collection654769 -Ref: Type656230 -Ref: Format660024 -Ref: Handling662326 -Ref: Post-processing663201 -Ref: Results of Evaluation-Footnote-1664951 -Node: Exporting Code Blocks665109 -Node: Extracting Source Code667462 -Ref: Header arguments668443 -Ref: Functions671984 -Ref: Tangle hooks672235 -Ref: Jumping between code and Org672484 -Node: Languages672994 -Node: Editing Source Code673987 -Node: Noweb Reference Syntax676717 -Ref: Noweb Reference Syntax-Footnote-1682865 -Node: Library of Babel682955 -Node: Key bindings and Useful Functions683673 -Node: Batch Execution686098 -Node: Miscellaneous686881 -Node: Completion688275 -Node: Structure Templates690200 -Ref: Structure Templates-Footnote-1691950 -Node: Speed Keys692042 -Node: Clean View693211 -Node: Org Indent Mode694413 -Ref: Org Indent Mode-Footnote-1695619 -Node: Hard indentation695843 -Ref: Hard indentation-Footnote-1697326 -Ref: Hard indentation-Footnote-2697432 -Node: Execute commands in the active region697576 -Node: Dynamic Headline Numbering698588 -Node: The Very Busy C-c C-c Key699754 -Node: In-buffer Settings701742 -Ref: In-buffer Settings-Footnote-1710848 -Node: Regular Expressions711046 -Node: Org Syntax711668 -Node: Documentation Access713326 -Node: Escape Character713747 -Node: Code Evaluation Security714608 -Node: Interaction717475 -Node: Cooperation717898 -Node: Conflicts720790 -Node: TTY Keys725392 -Node: Protocols726994 -Node: The store-link protocol728455 -Node: The capture protocol729598 -Node: The open-source protocol731231 -Node: Org Crypt734472 -Node: Org Mobile736085 -Node: Setting up the staging area737441 -Ref: Setting up the staging area-Footnote-1738681 -Ref: Setting up the staging area-Footnote-2738888 -Node: Pushing to the mobile application739060 -Ref: Pushing to the mobile application-Footnote-1740071 -Ref: Pushing to the mobile application-Footnote-2740162 -Ref: Pushing to the mobile application-Footnote-3740529 -Node: Pulling from the mobile application740605 -Ref: Pulling from the mobile application-Footnote-1742918 -Node: Hacking742971 -Node: Hooks743922 -Node: Add-on Packages744246 -Node: Adding Hyperlink Types744715 -Node: Adding Export Back-ends748310 -Node: Tables in Arbitrary Syntax749567 -Node: Radio tables750836 -Node: A LaTeX example752973 -Ref: A LaTeX example-Footnote-1756825 -Ref: A LaTeX example-Footnote-2756868 -Ref: A LaTeX example-Footnote-3757029 -Node: Translator functions757481 -Node: Dynamic Blocks759657 -Node: Special Agenda Views761903 -Ref: Special Agenda Views-Footnote-1765614 -Ref: Special Agenda Views-Footnote-2765821 -Node: Speeding Up Your Agendas765953 -Node: Extracting Agenda Information767012 -Node: Using the Property API770817 -Node: Using the Mapping API774172 -Node: History and Acknowledgments778208 -Ref: From Carsten778406 -Ref: From Bastien781837 -Ref: List of Contributions783969 -Node: GNU Free Documentation License792631 -Ref: ADDENDUM How to use this License for your documents816589 -Node: Main Index817982 -Node: Key Index915591 -Node: Command and Function Index972247 -Node: Variable Index1019293 - -End Tag Table - - -Local Variables: -coding: utf-8 -End: |