forked from mirrors/org-mode
21803 lines
763 KiB
Plaintext
21803 lines
763 KiB
Plaintext
\input texinfo @c -*- texinfo -*-
|
||
@c %**start of header
|
||
@setfilename org.info
|
||
@settitle The Org Manual
|
||
@documentencoding UTF-8
|
||
@documentlanguage en
|
||
@set txicodequoteundirected
|
||
@set txicodequotebacktick
|
||
@set MAINTAINERSITE @uref{https://orgmode.org,maintainers webpage}
|
||
@set MAINTAINER Carsten Dominik
|
||
@set MAINTAINEREMAIL @email{carsten at orgmode dot org}
|
||
@set MAINTAINERCONTACT @uref{mailto:carsten at orgmode dot org,contact the maintainer}
|
||
@c %**end of header
|
||
|
||
@copying
|
||
This manual is for Org version 9.1.
|
||
|
||
Copyright @copyright{} 2004--2018 Free Software Foundation, Inc.
|
||
|
||
@quotation
|
||
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.''
|
||
@end quotation
|
||
@end copying
|
||
|
||
@dircategory Emacs editing modes
|
||
@direntry
|
||
* Org Mode: (org). Outline-based notes management and organizer.
|
||
@end direntry
|
||
|
||
@finalout
|
||
@titlepage
|
||
@title The Org Manual
|
||
@subtitle Release 9.1
|
||
@author by Carsten Dominik
|
||
@author with contributions by Bastien Guerry, Nicolas Goaziou, Eric Schulte, Jambunathan K, Dan Davison, Thomas Dye, David O'Toole, and Philip Rooke.
|
||
@page
|
||
@vskip 0pt plus 1filll
|
||
@insertcopying
|
||
@end titlepage
|
||
|
||
@contents
|
||
|
||
@ifnottex
|
||
@node Top
|
||
@top The Org Manual
|
||
|
||
@insertcopying
|
||
@end ifnottex
|
||
|
||
@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.
|
||
* Capture, Refile, Archive: Capture Refile Archive. The ins and outs for projects.
|
||
* Agenda Views:: Collecting information into views.
|
||
* Markup:: Prepare text for rich export.
|
||
* Exporting:: Sharing and publishing notes.
|
||
* Publishing:: Create a web site of linked Org files.
|
||
* 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.
|
||
* MobileOrg:: Viewing and capture on a mobile device.
|
||
* 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.
|
||
|
||
@detailmenu
|
||
--- 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
|
||
|
||
* Outlines:: Org is based on Outline mode.
|
||
* 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.
|
||
* Creating Footnotes:: How footnotes are defined in Org's syntax.
|
||
* Org Syntax:: Formal description of Org's syntax.
|
||
|
||
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 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.
|
||
|
||
Capture, Refile, Archive
|
||
|
||
* Capture:: Capturing new stuff.
|
||
* Attachments:: Add files to tasks.
|
||
* RSS Feeds:: Getting input from RSS feeds.
|
||
* Protocols:: External access to Emacs and Org.
|
||
* Refile and Copy:: Moving/copying a tree from one place to another.
|
||
* Archiving:: What to do with finished products.
|
||
|
||
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.
|
||
|
||
Protocols
|
||
|
||
* @code{store-link} protocol:: Store a link, push URL to kill-ring.
|
||
* @code{capture} protocol:: Fill a buffer with external information.
|
||
* @code{open-source} protocol:: Edit published contents.
|
||
|
||
Archiving
|
||
|
||
* Moving subtrees:: Moving a tree to an archive file.
|
||
* Internal archiving:: Switch off a tree but keep it in the file.
|
||
|
||
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 times:: 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
|
||
|
||
* Paragraphs:: The basic unit of text.
|
||
* Emphasis and Monospace:: Bold, italic, etc.
|
||
* Horizontal Rules:: Make a line.
|
||
* Images and Tables:: Images, tables and caption mechanism.
|
||
* Literal Examples:: Source code examples with special formatting.
|
||
* Special Symbols:: Greek letters and other symbols.
|
||
* Subscripts and Superscripts:: Simple syntax for raising/lowering text.
|
||
* Embedded @LaTeX{}:: LaTeX can be freely used inside Org documents.
|
||
|
||
Embedded @LaTeX{}
|
||
|
||
* @LaTeX{} fragments:: Complex formulas made easy.
|
||
* Previewing @LaTeX{} fragments:: What will this snippet look like?
|
||
* CD@LaTeX{} 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::
|
||
* 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 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.
|
||
* 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.
|
||
|
||
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.
|
||
* Special blocks in Texinfo export:: Special block attributes.
|
||
* A Texinfo example:: Processing Org to Texinfo.
|
||
|
||
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.
|
||
|
||
Working with Source Code
|
||
|
||
* 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-@key{TAB} guesses completions.
|
||
* Structure Templates:: Quick insertion of structural elements.
|
||
* Speed Keys:: Electric commands at the beginning of a headline.
|
||
* Code Evaluation Security:: Org files evaluate in-line code.
|
||
* Customization:: Adapting Org to your taste.
|
||
* In-buffer Settings:: Overview of keywords.
|
||
* The Very Busy @kbd{C-c C-c} Key:: When in doubt, press @kbd{C-c C-c}.
|
||
* Clean View:: Getting rid of leading stars in the outline.
|
||
* TTY Keys:: Using Org on a tty.
|
||
* Interaction:: With other Emacs packages.
|
||
* Org Crypt:: Encrypting Org files.
|
||
|
||
Interaction
|
||
|
||
* Cooperation:: Packages Org cooperates with.
|
||
* Conflicts:: Packages that lead to conflicts.
|
||
|
||
Hacking
|
||
|
||
* Hooks: Hooks (2). 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.
|
||
|
||
MobileOrg
|
||
|
||
* Setting Up the Staging Area:: For the mobile device.
|
||
* Pushing to MobileOrg:: Uploading Org files and agendas.
|
||
* Pulling from MobileOrg:: Integrating captured and flagged items.
|
||
|
||
@end detailmenu
|
||
@end menu
|
||
|
||
@node Introduction
|
||
@chapter Introduction
|
||
|
||
@cindex 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.
|
||
@end menu
|
||
|
||
@node Summary
|
||
@section Summary
|
||
|
||
@cindex summary
|
||
|
||
Org is a mode for keeping notes, maintaining TODO lists, and project
|
||
planning with a fast and effective plain-text system. 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 makes use of metadata which is part of an outline
|
||
node. Based on this data, specific entries can be extracted in
|
||
queries and create dynamic @emph{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.
|
||
|
||
@cindex FAQ
|
||
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
|
||
@uref{https://orgmode.org}.
|
||
|
||
@cindex print edition
|
||
An earlier version (7.3) of this manual is available as a @uref{http://www.network-theory.co.uk/org/manual/, paperback
|
||
book from Network Theory Ltd.}.
|
||
|
||
@node Installation
|
||
@section Installation
|
||
|
||
@cindex installation
|
||
|
||
Org is part of recent distributions of GNU Emacs, so you normally do
|
||
not need to install it. If, for one reason or another, you want to
|
||
install Org on top of this pre-packaged version, there are three ways
|
||
to do it:
|
||
|
||
@itemize
|
||
@item
|
||
By using Emacs package system.
|
||
@item
|
||
By downloading Org as an archive.
|
||
@item
|
||
By using Org's git repository.
|
||
@end itemize
|
||
|
||
We @strong{strongly recommend} to stick to a single installation method.
|
||
|
||
@anchor{Using Emacs packaging system}
|
||
@subheading Using Emacs packaging system
|
||
|
||
Recent Emacs distributions include a packaging system which lets you
|
||
install Elisp libraries. You can install Org with @kbd{M-x package-install @key{RET} org}.
|
||
|
||
@noindent
|
||
@strong{Important}: you need to do this in a session where no @samp{.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.
|
||
|
||
Then, to make sure your Org configuration is taken into account,
|
||
initialize the package system with @code{(package-initialize)} in your
|
||
Emacs init file before setting any Org option. If you want to use
|
||
Org's package repository, check out the @uref{https://orgmode.org/elpa.html, Org ELPA page}.
|
||
|
||
@anchor{Downloading Org as an archive}
|
||
@subheading Downloading Org as an archive
|
||
|
||
You can download Org latest release from @uref{https://orgmode.org/, Org's website}. In this case,
|
||
make sure you set the load-path correctly in your Emacs init file:
|
||
|
||
@lisp
|
||
(add-to-list 'load-path "~/path/to/orgdir/lisp")
|
||
@end lisp
|
||
|
||
The downloaded archive contains contributed libraries that are not
|
||
included in Emacs. If you want to use them, add the @samp{contrib/}
|
||
directory to your load-path:
|
||
|
||
@lisp
|
||
(add-to-list 'load-path "~/path/to/orgdir/contrib/lisp" t)
|
||
@end lisp
|
||
|
||
Optionally, you can compile the files and/or install them in your
|
||
system. Run @samp{make help} to list compilation and installation options.
|
||
|
||
@anchor{Using Org's git repository}
|
||
@subheading Using Org's git repository
|
||
|
||
You can clone Org's repository and install Org like this:
|
||
|
||
@example
|
||
$ cd ~/src/
|
||
$ git clone git@@code.orgmode.org:bzg/org-mode.git
|
||
$ cd org-mode/
|
||
$ make autoloads
|
||
@end example
|
||
|
||
Note that in this case, @code{make autoloads} is mandatory: it defines
|
||
Org's version in @samp{org-version.el} and Org's autoloads in
|
||
@samp{org-loaddefs.el}.
|
||
|
||
Remember to add the correct load-path as described in the method
|
||
above.
|
||
|
||
You can also compile with @samp{make}, generate the documentation with
|
||
@samp{make doc}, create a local configuration with @samp{make config} and
|
||
install Org with @samp{make install}. Please run @samp{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 @uref{https://orgmode.org/worg/dev/org-build-system.html, Worg}.
|
||
|
||
@node Activation
|
||
@section Activation
|
||
|
||
@cindex activation
|
||
@cindex autoload
|
||
@cindex ELPA
|
||
@cindex global key bindings
|
||
@cindex key bindings, global
|
||
|
||
Org mode buffers need Font Lock to be turned on: this is the default
|
||
in Emacs@footnote{If you do not use Font Lock globally turn it on in Org buffer
|
||
with @code{(add-hook 'org-mode-hook 'turn-on-font-lock)}.}.
|
||
|
||
There are compatibility issues between Org mode and some other Elisp
|
||
packages (see @ref{Conflicts}). Please take the
|
||
time to check the list.
|
||
|
||
@findex org-agenda
|
||
@findex org-capture
|
||
@findex org-store-link
|
||
For a better experience, the three Org commands @code{org-store-link},
|
||
@code{org-capture} and @code{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
|
||
@ref{Key Binding Conventions,,,elisp,}). Here are suggested
|
||
bindings, please modify the keys to your own liking.
|
||
|
||
@lisp
|
||
(global-set-key "\C-cl" 'org-store-link)
|
||
(global-set-key "\C-ca" 'org-agenda)
|
||
(global-set-key "\C-cc" 'org-capture)
|
||
@end lisp
|
||
|
||
@cindex Org mode, turning on
|
||
Files with the @samp{.org} extension use Org mode by default. To turn on
|
||
Org mode in a file that does not have the extension @samp{.org}, make the
|
||
first line of a file look like this:
|
||
|
||
@example
|
||
MY PROJECTS -*- mode: org; -*-
|
||
@end example
|
||
|
||
@vindex org-insert-mode-line-in-empty-file
|
||
@noindent
|
||
which selects Org mode for this buffer no matter what the file's name
|
||
is. See also the variable @code{org-insert-mode-line-in-empty-file}.
|
||
|
||
Many commands in Org work on the region if the region is @emph{active}. To
|
||
make use of this, you need to have @code{transient-mark-mode} turned on,
|
||
which is the default. If you do not like @code{transient-mark-mode}, you
|
||
can create an active region by using the mouse to select a region, or
|
||
pressing @kbd{C-@key{SPC}} twice before moving the cursor.
|
||
|
||
@node Feedback
|
||
@section Feedback
|
||
|
||
@cindex feedback
|
||
@cindex bug reports
|
||
@cindex reporting a bug
|
||
@cindex maintainer
|
||
@cindex author
|
||
|
||
If you find problems with Org, or if you have questions, remarks, or
|
||
ideas about it, please mail to the Org mailing list
|
||
@email{emacs-orgmode@@gnu.org}. You can subscribe to the list @uref{https://lists.gnu.org/mailman/listinfo/emacs-orgmode, on this
|
||
web page}. If you are not a member of the mailing list, your mail will
|
||
be passed to the list after a moderator has approved it@footnote{Please consider subscribing to the mailing list in order to
|
||
minimize the work the mailing list moderators have to do.}.
|
||
|
||
@findex org-version
|
||
@findex org-submit-bug-report
|
||
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 (@kbd{M-x emacs-version}) and Org (@kbd{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
|
||
|
||
@example
|
||
M-x org-submit-bug-report <RET>
|
||
@end example
|
||
|
||
@noindent
|
||
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.
|
||
|
||
@example
|
||
$ emacs -Q -l /path/to/minimal-org.el
|
||
@end example
|
||
|
||
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 @samp{emacs -Q}. The @samp{minimal-org.el} setup file can have contents as
|
||
shown below.
|
||
|
||
@lisp
|
||
;;; 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"))
|
||
(add-to-list 'load-path (expand-file-name "/path/to/org-mode/contrib/lisp" t))
|
||
@end 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:
|
||
|
||
@enumerate
|
||
@item
|
||
What exactly did you do?
|
||
@item
|
||
What did you expect to happen?
|
||
@item
|
||
What happened instead?
|
||
@end enumerate
|
||
|
||
@noindent
|
||
Thank you for helping to improve this program.
|
||
|
||
@anchor{How to create a useful backtrace}
|
||
@subheading How to create a useful backtrace
|
||
|
||
@cindex backtrace of an error
|
||
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:
|
||
|
||
@enumerate
|
||
@item
|
||
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
|
||
|
||
@example
|
||
C-u M-x org-reload <RET>
|
||
@end example
|
||
|
||
@noindent
|
||
or, from the menu: Org @arrow{} Refresh/Reload @arrow{} Reload Org uncompiled.
|
||
|
||
@item
|
||
Then, activate the debugger:
|
||
|
||
@example
|
||
M-x toggle-debug-or-error <RET>
|
||
@end example
|
||
|
||
@noindent
|
||
or, from the menu: Options @arrow{} Enter Debugger on Error.
|
||
|
||
@item
|
||
Do whatever you have to do to hit the error. Do not forget to
|
||
document the steps you take.
|
||
|
||
@item
|
||
When you hit the error, a @samp{*Backtrace*} buffer appears on the
|
||
screen. Save this buffer to a file---for example using @kbd{C-x C-w}---and attach it to your bug report.
|
||
@end enumerate
|
||
|
||
@node Conventions
|
||
@section Typesetting Conventions Used in this Manual
|
||
|
||
|
||
|
||
@anchor{TODO keywords tags properties etc}
|
||
@subheading 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:
|
||
|
||
@table @asis
|
||
@item @samp{TODO}
|
||
@itemx @samp{WAITING}
|
||
TODO keywords are written with all capitals, even if they are
|
||
user-defined.
|
||
|
||
@item @samp{boss}
|
||
@itemx @samp{ARCHIVE}
|
||
User-defined tags are written in lowercase; built-in tags with
|
||
special meaning are written with all capitals.
|
||
|
||
@item @samp{Release}
|
||
@itemx @samp{PRIORITY}
|
||
User-defined properties are capitalized; built-in properties with
|
||
special meaning are written with all capitals.
|
||
|
||
@item @samp{TITLE}
|
||
@itemx @samp{BEGIN} @dots{} @samp{END}
|
||
Keywords and blocks are written in uppercase to enhance their
|
||
readability, but you can use lowercase in your Org files.
|
||
@end table
|
||
|
||
@anchor{Key bindings and commands}
|
||
@subheading 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 @code{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, @kbd{M-@key{RIGHT}} will be listed to call
|
||
@code{org-do-demote}, while in the chapter on tables, it will be listed to
|
||
call @code{org-table-move-column-right}.
|
||
|
||
@node Document Structure
|
||
@chapter Document Structure
|
||
|
||
@cindex document structure
|
||
@cindex structure of document
|
||
|
||
Org is based on Outline mode and provides flexible commands to
|
||
edit the structure of the document.
|
||
|
||
@menu
|
||
* Outlines:: Org is based on Outline mode.
|
||
* 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.
|
||
* Creating Footnotes:: How footnotes are defined in Org's syntax.
|
||
* Org Syntax:: Formal description of Org's syntax.
|
||
@end menu
|
||
|
||
@node Outlines
|
||
@section Outlines
|
||
|
||
@cindex outlines
|
||
@cindex Outline mode
|
||
|
||
Org is implemented on top of Outline mode. 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, @code{org-cycle}, which is bound to the @kbd{@key{TAB}} key.
|
||
|
||
@node Headlines
|
||
@section Headlines
|
||
|
||
@cindex headlines
|
||
@cindex outline tree
|
||
@vindex org-special-ctrl-a/e
|
||
@vindex org-special-ctrl-k
|
||
@vindex org-ctrl-k-protect-subtree
|
||
|
||
Headlines define the structure of an outline tree. The headlines in
|
||
Org start with one or more stars, on the left margin@footnote{See the variables @code{org-special-ctrl-a/e}, @code{org-special-ctrl-k},
|
||
and @code{org-ctrl-k-protect-subtree} to configure special behavior of
|
||
@kbd{C-a}, @kbd{C-e}, and @kbd{C-k} in headlines. Note
|
||
also that clocking only works with headings indented less than 30
|
||
stars.}. For
|
||
example:
|
||
|
||
@example
|
||
* Top level headline
|
||
** Second level
|
||
*** Third level
|
||
some text
|
||
*** Third level
|
||
more text
|
||
* Another top level headline
|
||
@end example
|
||
|
||
@vindex org-footnote-section
|
||
@noindent
|
||
Note that the name defined in @code{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.
|
||
See @ref{Clean View}.
|
||
|
||
@vindex org-cycle-separator-lines
|
||
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
|
||
@code{org-cycle-separator-lines} to modify this behavior.
|
||
|
||
@node Visibility Cycling
|
||
@section Visibility Cycling
|
||
|
||
@cindex cycling, visibility
|
||
@cindex visibility cycling
|
||
@cindex trees, visibility
|
||
@cindex show hidden text
|
||
@cindex hide text
|
||
|
||
@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.
|
||
@end menu
|
||
|
||
@node Global and local cycling
|
||
@subsection Global and local cycling
|
||
|
||
@cindex subtree visibility states
|
||
@cindex subtree cycling
|
||
@cindex folded, subtree visibility state
|
||
@cindex children, subtree visibility state
|
||
@cindex subtree, subtree visibility state
|
||
|
||
Outlines make it possible to hide parts of the text in the buffer.
|
||
Org uses just two commands, bound to @kbd{@key{TAB}} and
|
||
@kbd{S-@key{TAB}} to change the visibility in the buffer.
|
||
|
||
@table @asis
|
||
@item @kbd{@key{TAB}} (@code{org-cycle})
|
||
@kindex TAB
|
||
@findex org-cycle
|
||
@emph{Subtree cycling}: Rotate current subtree among the states
|
||
|
||
@example
|
||
,-> FOLDED -> CHILDREN -> SUBTREE --.
|
||
'-----------------------------------'
|
||
@end example
|
||
|
||
@vindex org-cycle-emulate-tab
|
||
The cursor must be on a headline for this to work@footnote{See, however, the option @code{org-cycle-emulate-tab}.}.
|
||
|
||
@item @kbd{S-@key{TAB}} (@code{org-global-cycle})
|
||
@itemx @kbd{C-u @key{TAB}}
|
||
@cindex global visibility states
|
||
@cindex global cycling
|
||
@cindex overview, global visibility state
|
||
@cindex contents, global visibility state
|
||
@cindex show all, global visibility state
|
||
@kindex C-u TAB
|
||
@kindex S-TAB
|
||
@findex org-global-cycle
|
||
@emph{Global cycling}: Rotate the entire buffer among the states
|
||
|
||
@example
|
||
,-> OVERVIEW -> CONTENTS -> SHOW ALL --.
|
||
'--------------------------------------'
|
||
@end example
|
||
|
||
When @kbd{S-@key{TAB}} is called with a numeric prefix argument N,
|
||
the CONTENTS view up to headlines of level N are shown. Note
|
||
that inside tables (see @ref{Tables}), @kbd{S-@key{TAB}} jumps to the
|
||
previous field instead.
|
||
|
||
@vindex org-cycle-global-at-bob
|
||
You can run global cycling using @kbd{@key{TAB}} only if point is
|
||
at the very beginning of the buffer, but not on a headline, and
|
||
@code{org-cycle-global-at-bob} is set to a non-@code{nil} value.
|
||
|
||
@item @kbd{C-u C-u @key{TAB}} (@code{org-set-startup-visibility})
|
||
@cindex startup visibility
|
||
@kindex C-u C-u TAB
|
||
@findex org-set-startup-visibility
|
||
Switch back to the startup visibility of the buffer (see @ref{Initial visibility}).
|
||
|
||
@item @kbd{C-u C-u C-u @key{TAB}} (@code{outline-show-all})
|
||
@cindex show all, command
|
||
@kindex C-u C-u C-u TAB
|
||
@findex outline-show-all
|
||
Show all, including drawers.
|
||
|
||
@item @kbd{C-c C-r} (@code{org-reveal})
|
||
@cindex revealing context
|
||
@kindex C-c C-r
|
||
@findex org-reveal
|
||
Reveal context around point, showing the current entry, the
|
||
following heading and the hierarchy above. Useful for working
|
||
near a location that has been exposed by a sparse tree command
|
||
(see @ref{Sparse Trees}) or an agenda command (see @ref{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.
|
||
|
||
@item @kbd{C-c C-k} (@code{outline-show-branches})
|
||
@cindex show branches, command
|
||
@kindex C-c C-k
|
||
@findex outline-show-branches
|
||
Expose all the headings of the subtree, CONTENTS view for just
|
||
one subtree.
|
||
|
||
@item @kbd{C-c @key{TAB}} (@code{outline-show-children})
|
||
@cindex show children, command
|
||
@kindex C-c TAB
|
||
@findex outline-show-children
|
||
Expose all direct children of the subtree. With a numeric prefix
|
||
argument N, expose all children down to level N.
|
||
|
||
@item @kbd{C-c C-x b} (@code{org-tree-to-indirect-buffer})
|
||
@kindex C-c C-x b
|
||
@findex org-tree-to-indirect-buffer
|
||
Show the current subtree in an indirect buffer@footnote{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 @ref{Indirect Buffers,GNU Emacs Manual,,emacs,}.}. 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 @kbd{C-u} prefix, do not remove the previously used
|
||
indirect buffer.
|
||
|
||
@item @kbd{C-c C-x v} (@code{org-copy-visible})
|
||
@kindex C-c C-x v
|
||
@findex org-copy-visible
|
||
Copy the @emph{visible} text in the region into the kill ring.
|
||
@end table
|
||
|
||
@node Initial visibility
|
||
@subsection Initial visibility
|
||
|
||
@vindex org-startup-folded
|
||
When Emacs first visits an Org file, the global state is set to
|
||
OVERVIEW, i.e., only the top level headlines are visible@footnote{When @code{org-agenda-inhibit-startup} is non-@code{nil}, Org does not
|
||
honor the default visibility state when first opening a file for the
|
||
agenda (see @ref{Speeding Up Your Agendas}).}. This
|
||
can be configured through the variable @code{org-startup-folded}, or on
|
||
a per-file basis by adding one of the following lines anywhere in the
|
||
buffer:
|
||
|
||
@cindex STARTUP, keyword
|
||
@example
|
||
#+STARTUP: overview
|
||
#+STARTUP: content
|
||
#+STARTUP: showall
|
||
#+STARTUP: showeverything
|
||
@end example
|
||
|
||
@cindex @samp{VISIBILITY}, property
|
||
@noindent
|
||
Furthermore, any entries with a @samp{VISIBILITY} property (see @ref{Properties and Columns}) get their visibility adapted accordingly. Allowed values
|
||
for this property are @samp{folded}, @samp{children}, @samp{content}, and @code{all}.
|
||
|
||
@table @asis
|
||
@item @kbd{C-u C-u @key{TAB}} (@code{org-set-startup-visibility})
|
||
@kindex C-u C-u TAB
|
||
@findex org-set-startup-visibility
|
||
Switch back to the startup visibility of the buffer, i.e.,
|
||
whatever is requested by startup options and @samp{VISIBILITY}
|
||
properties in individual entries.
|
||
@end table
|
||
|
||
@node Catching invisible edits
|
||
@subsection Catching invisible edits
|
||
|
||
@cindex edits, catching invisible
|
||
|
||
@vindex org-catch-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 @code{org-catch-invisible-edits} to non-@code{nil} helps preventing
|
||
this. See the docstring of this option on how Org should catch
|
||
invisible edits and process them.
|
||
|
||
@node Motion
|
||
@section Motion
|
||
|
||
@cindex motion, between headlines
|
||
@cindex jumping, to headlines
|
||
@cindex headline navigation
|
||
|
||
The following commands jump to other headlines in the buffer.
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-n} (@code{outline-next-visible-heading})
|
||
@kindex C-c C-n
|
||
@findex outline-next-visible-heading
|
||
Next heading.
|
||
|
||
@item @kbd{C-c C-p} (@code{outline-previous-visible-heading})
|
||
@kindex C-c C-p
|
||
@findex outline-previous-visible-heading
|
||
Previous heading.
|
||
|
||
@item @kbd{C-c C-f} (@code{org-forward-same-level})
|
||
@kindex C-c C-f
|
||
@findex org-forward-same-level
|
||
Next heading same level.
|
||
|
||
@item @kbd{C-c C-b} (@code{org-backward-same-level})
|
||
@kindex C-c C-b
|
||
@findex org-backward-same-level
|
||
Previous heading same level.
|
||
|
||
@item @kbd{C-c C-u} (@code{outline-up-heading})
|
||
@kindex C-c C-u
|
||
@findex outline-up-heading
|
||
Backward to higher level heading.
|
||
|
||
@item @kbd{C-c C-j} (@code{org-goto})
|
||
@kindex C-c C-j
|
||
@findex org-goto
|
||
@vindex org-goto-auto-isearch
|
||
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:
|
||
|
||
@multitable @columnfractions 0.3 0.7
|
||
@item @kbd{@key{TAB}}
|
||
@tab Cycle visibility.
|
||
@item @kbd{@key{DOWN}} / @kbd{@key{UP}}
|
||
@tab Next/previous visible headline.
|
||
@item @kbd{@key{RET}}
|
||
@tab Select this location.
|
||
@item @kbd{/}
|
||
@tab Do a Sparse-tree search
|
||
@end multitable
|
||
|
||
@noindent
|
||
The following keys work if you turn off @code{org-goto-auto-isearch}
|
||
|
||
@multitable @columnfractions 0.3 0.7
|
||
@item @kbd{n} / @kbd{p}
|
||
@tab Next/previous visible headline.
|
||
@item @kbd{f} / @kbd{b}
|
||
@tab Next/previous headline same level.
|
||
@item @kbd{u}
|
||
@tab One level up.
|
||
@item @kbd{0} @dots{} @kbd{9}
|
||
@tab Digit argument.
|
||
@item @kbd{q}
|
||
@tab Quit.
|
||
@end multitable
|
||
|
||
@vindex org-goto-interface
|
||
@noindent
|
||
See also the variable @code{org-goto-interface}.
|
||
@end table
|
||
|
||
@node Structure Editing
|
||
@section Structure Editing
|
||
|
||
@cindex structure editing
|
||
@cindex headline, promotion and demotion
|
||
@cindex promotion, of subtrees
|
||
@cindex demotion, of subtrees
|
||
@cindex subtree, cut and paste
|
||
@cindex pasting, of subtrees
|
||
@cindex cutting, of subtrees
|
||
@cindex copying, of subtrees
|
||
@cindex sorting, of subtrees
|
||
@cindex subtrees, cut and paste
|
||
|
||
@table @asis
|
||
@item @kbd{M-@key{RET}} (@code{org-meta-return})
|
||
@kindex M-RET
|
||
@findex org-meta-return
|
||
@vindex org-M-RET-may-split-line
|
||
Insert a new heading, item or row.
|
||
|
||
If the command is used at the @emph{beginning} of a line, and if there
|
||
is a heading or a plain list item (see @ref{Plain Lists}) at point,
|
||
the new heading/item is created @emph{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
|
||
@code{org-M-RET-may-split-line}.
|
||
|
||
Calling the command with a @kbd{C-u} prefix unconditionally
|
||
inserts a new heading at the end of the current subtree, thus
|
||
preserving its contents. With a double @kbd{C-u C-u}
|
||
prefix, the new heading is created at the end of the parent
|
||
subtree instead.
|
||
|
||
@item @kbd{C-@key{RET}} (@code{org-insert-heading-respect-content})
|
||
@kindex C-RET
|
||
@findex org-insert-heading-respect-content
|
||
Insert a new heading at the end of the current subtree.
|
||
|
||
@item @kbd{M-S-@key{RET}} (@code{org-insert-todo-heading})
|
||
@kindex M-S-RET
|
||
@findex org-insert-todo-heading
|
||
@vindex org-treat-insert-todo-heading-as-state-change
|
||
Insert new TODO entry with same level as current heading. See
|
||
also the variable
|
||
@code{org-treat-insert-todo-heading-as-state-change}.
|
||
|
||
@item @kbd{C-S-@key{RET}} (@code{org-insert-todo-heading-respect-content})
|
||
@kindex C-S-RET
|
||
@findex org-insert-todo-heading-respect-content
|
||
Insert new TODO entry with same level as current heading. Like
|
||
@kbd{C-@key{RET}}, the new headline is inserted after the current
|
||
subtree.
|
||
|
||
@item @kbd{@key{TAB}} (@code{org-cycle})
|
||
@kindex TAB
|
||
@findex org-cycle
|
||
In a new entry with no text yet, the first @kbd{@key{TAB}} demotes
|
||
the entry to become a child of the previous one. The next
|
||
@kbd{@key{TAB}} makes it a parent, and so on, all the way to top
|
||
level. Yet another @kbd{@key{TAB}}, and you are back to the
|
||
initial level.
|
||
|
||
@item @kbd{M-@key{LEFT}} (@code{org-do-promote})
|
||
@kindex M-LEFT
|
||
@findex org-do-promote
|
||
Promote current heading by one level.
|
||
|
||
@item @kbd{M-@key{RIGHT}} (@code{org-do-demote})
|
||
@kindex M-RIGHT
|
||
@findex org-do-demote
|
||
Demote current heading by one level.
|
||
|
||
@item @kbd{M-S-@key{LEFT}} (@code{org-promote-subtree})
|
||
@kindex M-S-LEFT
|
||
@findex org-promote-subtree
|
||
Promote the current subtree by one level.
|
||
|
||
@item @kbd{M-S-@key{RIGHT}} (@code{org-demote-subtree})
|
||
@kindex M-S-RIGHT
|
||
@findex org-demote-subtree
|
||
Demote the current subtree by one level.
|
||
|
||
@item @kbd{M-@key{UP}} (@code{org-move-subtree-up})
|
||
@kindex M-UP
|
||
@findex org-move-subtree-up
|
||
Move subtree up, i.e., swap with previous subtree of same level.
|
||
|
||
@item @kbd{M-@key{DOWN}} (@code{org-move-subtree-down})
|
||
@kindex M-DOWN
|
||
@findex org-move-subtree-down
|
||
Move subtree down, i.e., swap with next subtree of same level.
|
||
|
||
@item @kbd{C-c @@} (@code{org-mark-subtree})
|
||
@kindex C-c @@
|
||
@findex org-mark-subtree
|
||
Mark the subtree at point. Hitting repeatedly marks subsequent
|
||
subtrees of the same level as the marked subtree.
|
||
|
||
@item @kbd{C-c C-x C-w} (@code{org-cut-subtree})
|
||
@kindex C-c C-x C-w
|
||
@findex 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.
|
||
|
||
@item @kbd{C-c C-x M-w} (@code{org-copy-subtree})
|
||
@kindex C-c C-x M-w
|
||
@findex org-copy-subtree
|
||
Copy subtree to kill ring. With a numeric prefix argument N,
|
||
copy the N sequential subtrees.
|
||
|
||
@item @kbd{C-c C-x C-y} (@code{org-paste-subtree})
|
||
@kindex C-c C-x C-y
|
||
@findex 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
|
||
@samp{****}.
|
||
|
||
@item @kbd{C-y} (@code{org-yank})
|
||
@kindex C-y
|
||
@findex org-yank
|
||
@vindex org-yank-adjusted-subtrees
|
||
@vindex org-yank-folded-subtrees
|
||
Depending on the variables @code{org-yank-adjusted-subtrees} and
|
||
@code{org-yank-folded-subtrees}, Org's internal @code{yank} command pastes
|
||
subtrees folded and in a clever way, using the same command as
|
||
@kbd{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 @code{yank} to be executed,
|
||
with the prefix passed along. A good way to force a normal yank
|
||
is @kbd{C-u C-y}. If you use @code{yank-pop} after a yank, it
|
||
yanks previous kill items plainly, without adjustment and
|
||
folding.
|
||
|
||
@item @kbd{C-c C-x c} (@code{org-clone-subtree-with-time-shift})
|
||
@kindex C-c C-x c
|
||
@findex 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 @code{org-clone-subtree-with-time-shift}.
|
||
|
||
@item @kbd{C-c C-w} (@code{org-refile})
|
||
@kindex C-c C-w
|
||
@findex org-refile
|
||
Refile entry or region to a different location. See @ref{Refile and Copy}.
|
||
|
||
@item @kbd{C-c ^} (@code{org-sort})
|
||
@kindex C-c ^
|
||
@findex 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 @kbd{C-u} prefix, sorting is case-sensitive.
|
||
|
||
@item @kbd{C-x n s} (@code{org-narrow-to-subtree})
|
||
@kindex C-x n s
|
||
@findex org-narrow-to-subtree
|
||
Narrow buffer to current subtree.
|
||
|
||
@item @kbd{C-x n b} (@code{org-narrow-to-block})
|
||
@kindex C-x n b
|
||
@findex org-narrow-to-block
|
||
Narrow buffer to current block.
|
||
|
||
@item @kbd{C-x n w} (@code{widen})
|
||
@kindex C-x n w
|
||
@findex widen
|
||
Widen buffer to remove narrowing.
|
||
|
||
@item @kbd{C-c *} (@code{org-toggle-heading})
|
||
@kindex C-c *
|
||
@findex 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.
|
||
@end table
|
||
|
||
@cindex region, active
|
||
@cindex active region
|
||
@cindex transient mark mode
|
||
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. Note that when the cursor is inside a table (see @ref{Tables}),
|
||
the Meta-Cursor keys have different functionality.
|
||
|
||
@node Sparse Trees
|
||
@section Sparse Trees
|
||
|
||
@cindex sparse trees
|
||
@cindex trees, sparse
|
||
@cindex folding, sparse trees
|
||
@cindex occur, command
|
||
|
||
@vindex org-show-context-detail
|
||
An important feature of Org mode is the ability to construct @emph{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@footnote{See also the variable @code{org-show-context-detail} to decide how
|
||
much context is shown around each match.}.
|
||
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:
|
||
|
||
@table @asis
|
||
@item @kbd{C-c /} (@code{org-sparse-tree})
|
||
@kindex C-c /
|
||
@findex org-sparse-tree
|
||
This prompts for an extra key to select a sparse-tree creating
|
||
command.
|
||
|
||
@item @kbd{C-c / r} or @kbd{C-c / /} (@code{org-occur})
|
||
@kindex C-c / r
|
||
@kindex C-c / /
|
||
@findex org-occur
|
||
@vindex org-remove-highlights-with-change
|
||
Prompts for a regexp 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 @kbd{C-c C-c}@footnote{This depends on the option @code{org-remove-highlights-with-change}.}. When called
|
||
with a @kbd{C-u} prefix argument, previous highlights are
|
||
kept, so several calls to this command can be stacked.
|
||
|
||
@item @kbd{M-g n} or @kbd{M-g M-n} (@code{next-error})
|
||
@kindex M-g n
|
||
@kindex M-g M-n
|
||
@findex next-error
|
||
Jump to the next sparse tree match in this buffer.
|
||
|
||
@item @kbd{M-g p} or @kbd{M-g M-p} (@code{previous-error})
|
||
@kindex M-g p
|
||
@kindex M-g M-p
|
||
@findex previous-error
|
||
Jump to the previous sparse tree match in this buffer.
|
||
@end table
|
||
|
||
@vindex org-agenda-custom-commands
|
||
@noindent
|
||
For frequently used sparse trees of specific search strings, you can
|
||
use the variable @code{org-agenda-custom-commands} to define fast keyboard
|
||
access to specific sparse trees. These commands will then be
|
||
accessible through the agenda dispatcher (see @ref{Agenda Dispatcher}).
|
||
For example:
|
||
|
||
@lisp
|
||
(setq org-agenda-custom-commands
|
||
'(("f" occur-tree "FIXME")))
|
||
@end lisp
|
||
|
||
@noindent
|
||
defines the key @kbd{f} as a shortcut for creating a sparse tree
|
||
matching the string @samp{FIXME}.
|
||
|
||
The other sparse tree commands select headings based on TODO keywords,
|
||
tags, or properties and are discussed later in this manual.
|
||
|
||
@kindex C-c C-e v
|
||
@cindex printing sparse trees
|
||
@cindex visible text, printing
|
||
To print a sparse tree, you can use the Emacs command
|
||
@code{ps-print-buffer-with-faces} which does not print invisible parts of
|
||
the document. Or you can use the command @kbd{C-c C-e v} to
|
||
export only the visible part of the document and print the resulting
|
||
file.
|
||
|
||
@node Plain Lists
|
||
@section Plain Lists
|
||
|
||
@cindex plain lists
|
||
@cindex lists, plain
|
||
@cindex lists, ordered
|
||
@cindex ordered 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 @ref{Checkboxes}). Org supports editing such lists, and
|
||
every exporter (see @ref{Exporting}) can parse and format them.
|
||
|
||
Org knows ordered lists, unordered lists, and description lists.
|
||
|
||
@itemize
|
||
@item
|
||
@emph{Unordered} list items start with @samp{-}, @samp{+}, or @samp{*}@footnote{When using @samp{*} 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 @samp{*} is supported, it may be better to not use it for plain list
|
||
items.} as bullets.
|
||
|
||
@item
|
||
@vindex org-plain-list-ordered-item-terminator
|
||
@vindex org-alphabetical-lists
|
||
@emph{Ordered} list items start with a numeral followed by either
|
||
a period or a right parenthesis@footnote{You can filter out any of them by configuring
|
||
@code{org-plain-list-ordered-item-terminator}.}, such as @samp{1.} or @samp{1)}@footnote{You can also get @samp{a.}, @samp{A.}, @samp{a)} and @samp{A)} by configuring
|
||
@code{org-list-allow-alphabetical}. To minimize confusion with normal
|
||
text, those are limited to one character only. Beyond that limit,
|
||
bullets automatically become numbers.}
|
||
If you want a list to start with a different value---e.g.,
|
||
20---start the text of the item with @samp{[@@20]}@footnote{If there's a checkbox in the item, the cookie must be put
|
||
@emph{before} the checkbox. If you have activated alphabetical lists, you
|
||
can also use counters like @samp{[@@b]}.}. Those
|
||
constructs can be used in any item of the list in order to enforce
|
||
a particular numbering.
|
||
|
||
@item
|
||
@emph{Description} list items are unordered list items, and contain the
|
||
separator @samp{::} to distinguish the description @emph{term} from the
|
||
description.
|
||
@end itemize
|
||
|
||
Items belonging to the same list must have the same indentation on the
|
||
first line. In particular, if an ordered list reaches number @samp{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:
|
||
|
||
@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/.
|
||
@end example
|
||
|
||
Org supports these lists by tuning filling and wrapping commands to
|
||
deal with them correctly, and by exporting them properly (see
|
||
@ref{Exporting}). Since indentation is what governs the structure of these
|
||
lists, many structural constructs like @samp{#+BEGIN_} blocks can be
|
||
indented to signal that they belong to a particular item.
|
||
|
||
@vindex org-list-demote-modify-bullet
|
||
@vindex org-list-indent-offset
|
||
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 @code{org-list-demote-modify-bullet}. To get a greater difference
|
||
of indentation between items and theirs sub-items, customize
|
||
@code{org-list-indent-offset}.
|
||
|
||
@vindex org-list-automatic-rules
|
||
The following commands act on items when the cursor 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
|
||
@code{org-list-automatic-rules} to disable them individually.
|
||
|
||
@table @asis
|
||
@item @kbd{@key{TAB}} (@code{org-cycle})
|
||
@cindex cycling, in plain lists
|
||
@kindex TAB
|
||
@findex org-cycle
|
||
@vindex org-cycle-include-plain-lists
|
||
Items can be folded just like headline levels. Normally this
|
||
works only if the cursor is on a plain list item. For more
|
||
details, see the variable @code{org-cycle-include-plain-lists}. If
|
||
this variable is set to @code{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
|
||
@kbd{@key{TAB}} demotes the item to become a child of the previous
|
||
one. Subsequent @kbd{@key{TAB}}s move the item to meaningful
|
||
levels in the list and eventually get it back to its initial
|
||
position.
|
||
|
||
@item @kbd{M-@key{RET}} (@code{org-insert-heading})
|
||
@kindex M-RET
|
||
@findex org-insert-heading
|
||
@vindex org-M-RET-may-split-line
|
||
Insert new item at current level. With a prefix argument, force
|
||
a new heading (see @ref{Structure Editing}). If this command is used
|
||
in the middle of an item, that item is @emph{split} in two, and the
|
||
second part becomes the new item@footnote{If you do not want the item to be split, customize the
|
||
variable @code{org-M-RET-may-split-line}.}. If this command is
|
||
executed @emph{before item's body}, the new item is created @emph{before}
|
||
the current one.
|
||
|
||
@item @kbd{M-S-@key{RET}}
|
||
@kindex M-S-RET
|
||
Insert a new item with a checkbox (see @ref{Checkboxes}).
|
||
|
||
@item @kbd{S-@key{UP}}
|
||
@itemx @kbd{S-@key{DOWN}}
|
||
@kindex S-UP
|
||
@kindex S-DOWN
|
||
@cindex shift-selection-mode
|
||
@vindex org-support-shift-select
|
||
@vindex org-list-use-circular-motion
|
||
Jump to the previous/next item in the current list, but only if
|
||
@code{org-support-shift-select} is off@footnote{If you want to cycle around items that way, you may customize
|
||
@code{org-list-use-circular-motion}.}. If not, you can
|
||
still use paragraph jumping commands like @kbd{C-@key{UP}}
|
||
and @kbd{C-@key{DOWN}} to quite similar effect.
|
||
|
||
@item @kbd{M-@key{UP}}
|
||
@itemx @kbd{M-@key{DOWN}}
|
||
@kindex M-UP
|
||
@kindex M-DOWN
|
||
Move the item including subitems up/down@footnote{See @code{org-list-use-circular-motion} for a cyclic behavior.}, i.e., swap with
|
||
previous/next item of same indentation. If the list is ordered,
|
||
renumbering is automatic.
|
||
|
||
@item @kbd{M-@key{LEFT}}
|
||
@itemx @kbd{M-@key{RIGHT}}
|
||
@kindex M-LEFT
|
||
@kindex M-RIGHT
|
||
Decrease/increase the indentation of an item, leaving children
|
||
alone.
|
||
|
||
@item @kbd{M-S-@key{LEFT}}
|
||
@itemx @kbd{M-S-@key{RIGHT}}
|
||
@kindex M-S-LEFT
|
||
@kindex 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 with a cursor motion
|
||
or so.
|
||
|
||
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 @code{org-list-automatic-rules}. The global indentation
|
||
of a list has no influence on the text @emph{after} the list.
|
||
|
||
@item @kbd{C-c C-c}
|
||
@kindex C-c C-c
|
||
If there is a checkbox (see @ref{Checkboxes}) in the item line, toggle
|
||
the state of the checkbox. In any case, verify bullets and
|
||
indentation consistency in the whole list.
|
||
|
||
@item @kbd{C-c -}
|
||
@kindex C-c -
|
||
@vindex org-plain-list-ordered-item-terminator
|
||
Cycle the entire list level through the different
|
||
itemize/enumerate bullets (@samp{-}, @samp{+}, @samp{*}, @samp{1.}, @samp{1)}) or a subset
|
||
of them, depending on @code{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, selected text is changed into an
|
||
item. With a prefix argument, all lines are converted to list
|
||
items. 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.
|
||
|
||
@item @kbd{C-c *}
|
||
@kindex C-c *
|
||
Turn a plain list item into a headline---so that it becomes
|
||
a subheading at its location. See @ref{Structure Editing}, for
|
||
a detailed explanation.
|
||
|
||
@item @kbd{C-c C-*}
|
||
@kindex C-c C-*
|
||
Turn the whole plain list into a subtree of the current heading.
|
||
Checkboxes (see @ref{Checkboxes}) become TODO, respectively DONE,
|
||
keywords when unchecked, respectively checked.
|
||
|
||
@item @kbd{S-@key{LEFT}}
|
||
@itemx @kbd{S-@key{RIGHT}}
|
||
@vindex org-support-shift-select
|
||
@kindex S-LEFT
|
||
@kindex S-RIGHT
|
||
This command also cycles bullet styles when the cursor in on the
|
||
bullet or anywhere in an item line, details depending on
|
||
@code{org-support-shift-select}.
|
||
|
||
@item @kbd{C-c ^}
|
||
@kindex C-c ^
|
||
@cindex sorting, of plain list
|
||
Sort the plain list. Prompt for the sorting method: numerically,
|
||
alphabetically, by time, or by custom function.
|
||
@end table
|
||
|
||
@node Drawers
|
||
@section Drawers
|
||
|
||
@cindex drawers
|
||
@cindex visibility cycling, 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 @emph{drawers}.
|
||
They can contain anything but a headline and another drawer. Drawers
|
||
look like this:
|
||
|
||
@example
|
||
** This is a headline
|
||
Still outside the drawer
|
||
:DRAWERNAME:
|
||
This is inside the drawer.
|
||
:END:
|
||
After the drawer.
|
||
@end example
|
||
|
||
@kindex C-c C-x d
|
||
@findex org-insert-drawer
|
||
You can interactively insert a drawer at point by calling
|
||
@code{org-insert-drawer}, which is bound to @kbd{C-c C-x d}. With an
|
||
active region, this command puts the region inside the drawer. With
|
||
a prefix argument, this command calls @code{org-insert-property-drawer},
|
||
which creates a @samp{PROPERTIES} drawer right below the current headline.
|
||
Org mode uses this special drawer for storing properties (see
|
||
@ref{Properties and Columns}). You cannot use it for anything else.
|
||
|
||
Completion over drawer keywords is also possible using
|
||
@kbd{M-@key{TAB}}@footnote{Many desktops intercept @kbd{M-@key{TAB}} to switch windows.
|
||
Use @kbd{C-M-i} or @kbd{@key{ESC} @key{TAB}} instead.}.
|
||
|
||
Visibility cycling (see @ref{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 the cursor to the
|
||
drawer line and press @kbd{@key{TAB}} there.
|
||
|
||
You can also arrange for state change notes (see @ref{Tracking TODO state changes}) and clock times (see @ref{Clocking Work Time}) to be stored in
|
||
a @samp{LOGBOOK} drawer. If you want to store a quick note there, in
|
||
a similar way to state changes, use
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-z}
|
||
@kindex C-c C-z
|
||
Add a time-stamped note to the @samp{LOGBOOK} drawer.
|
||
@end table
|
||
|
||
@node Blocks
|
||
@section Blocks
|
||
|
||
@vindex org-hide-block-startup
|
||
@cindex blocks, folding
|
||
|
||
Org mode uses @samp{#+BEGIN} @dots{} @samp{#+END} blocks for various purposes from
|
||
including source code examples (see @ref{Literal Examples}) to capturing
|
||
time logging information (see @ref{Clocking Work Time}). These blocks can
|
||
be folded and unfolded by pressing @kbd{@key{TAB}} in the @samp{#+BEGIN}
|
||
line. You can also get all blocks folded at startup by configuring
|
||
the variable @code{org-hide-block-startup} or on a per-file basis by using
|
||
|
||
@cindex STARTUP, keyword
|
||
@example
|
||
#+STARTUP: hideblocks
|
||
#+STARTUP: nohideblocks
|
||
@end example
|
||
|
||
@node Creating Footnotes
|
||
@section Creating Footnotes
|
||
|
||
@cindex footnotes
|
||
|
||
Org mode supports the creation of 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 @samp{fn:}. For example:
|
||
|
||
@example
|
||
The Org homepage[fn:1] now looks a lot better than it used to.
|
||
...
|
||
[fn:1] The link is: https://orgmode.org
|
||
@end example
|
||
|
||
Org mode extends the number-based syntax to @emph{named} footnotes and
|
||
optional inline definition. Here are the valid references:
|
||
|
||
@table @asis
|
||
@item @samp{[fn:NAME]}
|
||
A named footnote reference, where @var{NAME} is a unique
|
||
label word, or, for simplicity of automatic creation, a number.
|
||
|
||
@item @samp{[fn:: This is the inline definition of this footnote]}
|
||
A @LaTeX{}-like anonymous footnote where the definition is given
|
||
directly at the reference point.
|
||
|
||
@item @samp{[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 @samp{[fn:NAME]} to create additional
|
||
references.
|
||
@end table
|
||
|
||
@vindex org-footnote-auto-label
|
||
Footnote labels can be created automatically, or you can create names
|
||
yourself. This is handled by the variable @code{org-footnote-auto-label}
|
||
and its corresponding @samp{STARTUP} keywords. See the docstring of that
|
||
variable for details.
|
||
|
||
@noindent
|
||
The following command handles footnotes:
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-x f}
|
||
The footnote action command.
|
||
|
||
@kindex C-c C-x f
|
||
When the cursor is on a footnote reference, jump to the
|
||
definition. When it is at a definition, jump to
|
||
the---first---reference.
|
||
|
||
@vindex org-footnote-define-inline
|
||
@vindex org-footnote-section
|
||
Otherwise, create a new footnote. Depending on the variable
|
||
@code{org-footnote-define-inline}@footnote{The corresponding in-buffer setting is: @samp{#+STARTUP: fninline}
|
||
or @samp{#+STARTUP: nofninline}.}, the definition is placed
|
||
right into the text as part of the reference, or separately into
|
||
the location determined by the variable @code{org-footnote-section}.
|
||
|
||
When this command is called with a prefix argument, a menu of
|
||
additional options is offered:
|
||
|
||
@multitable @columnfractions 0.1 0.9
|
||
@item @kbd{s}
|
||
@tab Sort the footnote definitions by reference sequence.
|
||
@item @kbd{r}
|
||
@tab Renumber the simple @samp{fn:N} footnotes.
|
||
@item @kbd{S}
|
||
@tab Short for first @kbd{r}, then @kbd{s} action.
|
||
@item @kbd{n}
|
||
@tab Rename all footnotes into a @samp{fn:1} @dots{} @samp{fn:n} sequence.
|
||
@item @kbd{d}
|
||
@tab Delete the footnote at point, including definition and references.
|
||
@end multitable
|
||
|
||
@vindex org-footnote-auto-adjust
|
||
Depending on the variable @code{org-footnote-auto-adjust}@footnote{The corresponding in-buffer options are @samp{#+STARTUP: fnadjust}
|
||
and @samp{#+STARTUP: nofnadjust}.},
|
||
renumbering and sorting footnotes can be automatic after each
|
||
insertion or deletion.
|
||
|
||
@item @kbd{C-c C-c}
|
||
@kindex C-c C-c
|
||
If the cursor 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 @kbd{C-c C-x f}.
|
||
|
||
@item @kbd{C-c C-o} or @kbd{mouse-1/2}
|
||
@kindex C-c C-o
|
||
@kindex mouse-1
|
||
@kindex mouse-2
|
||
Footnote labels are also links to the corresponding definition or
|
||
reference, and you can use the usual commands to follow these
|
||
links.
|
||
@end table
|
||
|
||
@node Org Syntax
|
||
@section Org Syntax
|
||
|
||
A reference document providing a formal description of Org's syntax is
|
||
available as @uref{https://orgmode.org/worg/dev/org-syntax.html, a draft on Worg}, written and maintained by Nicolas
|
||
Goaziou. It defines Org's core internal concepts such as @samp{headlines},
|
||
@samp{sections}, @samp{affiliated keywords}, @samp{(greater) elements} and @samp{objects}.
|
||
Each part of an Org file falls into one of the categories above.
|
||
|
||
To explore the abstract structure of an Org buffer, run this in
|
||
a buffer:
|
||
|
||
@example
|
||
M-: (org-element-parse-buffer) <RET>
|
||
@end example
|
||
|
||
@noindent
|
||
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.
|
||
|
||
@cindex syntax checker
|
||
@cindex linter
|
||
@findex org-lint
|
||
You can check syntax in your documents using @code{org-lint} command.
|
||
|
||
@node Tables
|
||
@chapter Tables
|
||
|
||
@cindex tables
|
||
@cindex editing tables
|
||
|
||
Org comes with a fast and intuitive table editor. Spreadsheet-like
|
||
calculations are supported using the Emacs Calc package (see @ref{Top,GNU Emacs
|
||
Calculator Manual,,calc,}).
|
||
|
||
@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.
|
||
@end menu
|
||
|
||
@node Built-in Table Editor
|
||
@section Built-in Table Editor
|
||
|
||
@cindex table editor, built-in
|
||
|
||
Org makes it easy to format tables in plain ASCII. Any line with @samp{|}
|
||
as the first non-whitespace character is considered part of a table.
|
||
@samp{|} is also the column separator@footnote{To insert a vertical bar into a table field, use @samp{\vert} or,
|
||
inside a word @samp{abc\vert@{@}def}.}. A table might look like
|
||
this:
|
||
|
||
@example
|
||
| Name | Phone | Age |
|
||
|-------+-------+-----|
|
||
| Peter | 1234 | 17 |
|
||
| Anna | 4321 | 25 |
|
||
@end example
|
||
|
||
A table is re-aligned automatically each time you press
|
||
@kbd{@key{TAB}}, @kbd{@key{RET}} or @kbd{C-c C-c} inside the table.
|
||
@kbd{@key{TAB}} also moves to the next field---@kbd{@key{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. Any line starting with @samp{|-} is considered as a horizontal
|
||
separator line and will be expanded on the next re-align to span the
|
||
whole table width. So, to create the above table, you would only type
|
||
|
||
@example
|
||
|Name|Phone|Age|
|
||
|-
|
||
@end example
|
||
|
||
@noindent
|
||
and then press @kbd{@key{TAB}} to align the table and start filling in
|
||
fields. Even faster would be to type @samp{|Name|Phone|Age} followed by
|
||
@kbd{C-c @key{RET}}.
|
||
|
||
When typing text into a field, Org treats @kbd{DEL},
|
||
@kbd{Backspace}, and all character keys in a special way, so that
|
||
inserting and deleting avoids shifting other fields. Also, when
|
||
typing @emph{immediately} after the cursor was moved into a new field with
|
||
@kbd{@key{TAB}}, @kbd{S-@key{TAB}} or @kbd{@key{RET}}, the field is
|
||
automatically made blank. If this behavior is too unpredictable for
|
||
you, configure the option @code{org-table-auto-blank-field}.
|
||
|
||
@anchor{Creation and conversion}
|
||
@subheading Creation and conversion
|
||
|
||
@table @asis
|
||
@item @kbd{C-c |} (@code{org-table-create-or-convert-from-region})
|
||
@kindex C-c |
|
||
@findex org-table-create-or-convert-from-region
|
||
Convert the active region to table. If every line contains at
|
||
least one @kbd{@key{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: @kbd{C-u} forces CSV,
|
||
@kbd{C-u C-u} forces @kbd{@key{TAB}}, @kbd{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 @kbd{@key{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 @kbd{| N a m e | P h o n e | A g e @key{RET} | - @key{TAB}}.
|
||
@end table
|
||
|
||
@anchor{Re-aligning and field motion}
|
||
@subheading Re-aligning and field motion
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-c} (@code{org-table-align})
|
||
@kindex C-c C-c
|
||
@findex org-table-align
|
||
Re-align the table without moving the cursor.
|
||
|
||
@item @kbd{@key{TAB}} (@code{org-table-next-field})
|
||
@kindex TAB
|
||
@findex org-table-next-field
|
||
Re-align the table, move to the next field. Creates a new row if
|
||
necessary.
|
||
|
||
@item @kbd{C-c @key{SPC}} (@code{org-table-blank-field})
|
||
@kindex C-c SPC
|
||
@findex org-table-blank-field
|
||
Blank the field at point.
|
||
|
||
@item @kbd{S-@key{TAB}} (@code{org-table-previous-field})
|
||
@kindex S-TAB
|
||
@findex org-table-previous-field
|
||
Re-align, move to previous field.
|
||
|
||
@item @kbd{@key{RET}} (@code{org-table-next-row})
|
||
@kindex RET
|
||
@findex 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, @kbd{@key{RET}}
|
||
still inserts a new line, so it can be used to split a table.
|
||
|
||
@item @kbd{M-a} (@code{org-table-beginning-of-field})
|
||
@kindex M-a
|
||
@findex org-table-beginning-of-field
|
||
Move to beginning of the current table field, or on to the
|
||
previous field.
|
||
|
||
@item @kbd{M-e} (@code{org-table-end-of-field})
|
||
@kindex M-e
|
||
@findex org-table-end-of-field
|
||
Move to end of the current table field, or on to the next field.
|
||
@end table
|
||
|
||
@anchor{Column and row editing}
|
||
@subheading Column and row editing
|
||
|
||
@table @asis
|
||
@item @kbd{M-@key{LEFT}} (@code{org-table-move-column-left})
|
||
@kindex M-LEFT
|
||
@findex org-table-move-column-left
|
||
Move the current column left.
|
||
|
||
@item @kbd{M-@key{RIGHT}} (@code{org-table-move-column-right})
|
||
@kindex M-RIGHT
|
||
@findex org-table-move-column-right
|
||
Move the current column right.
|
||
|
||
@item @kbd{M-S-@key{LEFT}} (@code{org-table-delete-column})
|
||
@kindex M-S-LEFT
|
||
@findex org-table-delete-column
|
||
Kill the current column.
|
||
|
||
@item @kbd{M-S-@key{RIGHT}} (@code{org-table-insert-column})
|
||
@kindex M-S-RIGHT
|
||
@findex org-table-insert-column
|
||
Insert a new column to the left of the cursor position.
|
||
|
||
@item @kbd{M-@key{UP}} (@code{org-table-move-row-up})
|
||
@kindex M-UP
|
||
@findex org-table-move-row-up
|
||
Move the current row up.
|
||
|
||
@item @kbd{M-@key{DOWN}} (@code{org-table-move-row-down})
|
||
@kindex M-DOWN
|
||
@findex org-table-move-row-down
|
||
Move the current row down.
|
||
|
||
@item @kbd{M-S-@key{UP}} (@code{org-table-kill-row})
|
||
@kindex M-S-UP
|
||
@findex org-table-kill-row
|
||
Kill the current row or horizontal line.
|
||
|
||
@item @kbd{M-S-@key{DOWN}} (@code{org-table-insert-row})
|
||
@kindex M-S-DOWN
|
||
@findex org-table-insert-row
|
||
Insert a new row above the current row. With a prefix argument,
|
||
the line is created below the current one.
|
||
|
||
@item @kbd{C-c -} (@code{org-table-insert-hline})
|
||
@kindex C-c -
|
||
@findex org-table-insert-hline
|
||
Insert a horizontal line below current row. With a prefix
|
||
argument, the line is created above the current line.
|
||
|
||
@item @kbd{C-c @key{RET}} (@code{org-table-hline-and-move})
|
||
@kindex C-c RET
|
||
@findex org-table-hline-and-move
|
||
Insert a horizontal line below current row, and move the cursor
|
||
into the row below that line.
|
||
|
||
@item @kbd{C-c ^} (@code{org-table-sort-lines})
|
||
@kindex C-c ^
|
||
@findex 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.
|
||
@end table
|
||
|
||
@anchor{Regions}
|
||
@subheading Regions
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-x M-w} (@code{org-table-copy-region})
|
||
@kindex C-c C-x M-w
|
||
@findex 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.
|
||
|
||
@item @kbd{C-c C-x C-w} (@code{org-table-cut-region})
|
||
@kindex C-c C-x C-w
|
||
@findex 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.
|
||
|
||
@item @kbd{C-c C-x C-y} (@code{org-table-paste-rectangle})
|
||
@kindex C-c C-x C-y
|
||
@findex 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.
|
||
|
||
@item @kbd{M-@key{RET}} (@code{org-table-wrap-region})
|
||
@kindex M-RET
|
||
@findex org-table-wrap-region
|
||
Split the current field at the cursor 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.
|
||
@end table
|
||
|
||
@anchor{Calculations}
|
||
@subheading Calculations
|
||
|
||
@cindex formula, in tables
|
||
@cindex calculations, in tables
|
||
|
||
@table @asis
|
||
@item @kbd{C-c +} (@code{org-table-sum})
|
||
@kindex C-c +
|
||
@findex 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 @kbd{C-y}.
|
||
|
||
@item @kbd{S-@key{RET}} (@code{org-table-copy-down})
|
||
@kindex S-RET
|
||
@findex org-table-copy-down
|
||
@vindex org-table-copy-increment
|
||
When current field is empty, copy from first non-empty field
|
||
above. When not empty, copy current field down to next row and
|
||
move cursor along with it. Depending on the variable
|
||
@code{org-table-copy-increment}, integer field values can be
|
||
incremented during copy. Integers that are too large are not
|
||
incremented, however. Also, a @code{0} prefix argument temporarily
|
||
disables the increment. This key is also used by shift-selection
|
||
and related modes (see @ref{Conflicts}).
|
||
@end table
|
||
|
||
@anchor{Miscellaneous (1)}
|
||
@subheading Miscellaneous
|
||
|
||
@table @asis
|
||
@item @kbd{C-c `} (@code{org-table-edit-field})
|
||
@kindex C-c `
|
||
@findex org-table-edit-field
|
||
Edit the current field in a separate window. This is useful for
|
||
fields that are not fully visible (see @ref{Column Width and Alignment}). When called with a @kbd{C-u} prefix, just make
|
||
the full field visible, so that it can be edited in place. When
|
||
called with two @kbd{C-u} prefixes, make the editor window
|
||
follow the cursor through the table and always show the current
|
||
field. The follow mode exits automatically when the cursor
|
||
leaves the table, or when you repeat this command with @kbd{C-u C-u C-c `}.
|
||
|
||
@item @kbd{M-x org-table-import}
|
||
@findex 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.
|
||
|
||
@item @kbd{C-c |} (@code{org-table-create-or-convert-from-region})
|
||
@kindex C-c |
|
||
@findex 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 @kbd{C-x C-x} and
|
||
then using the @kbd{C-c |} command (see @ref{Creation and conversion}).
|
||
|
||
@item @kbd{M-x org-table-export}
|
||
@findex org-table-export
|
||
@vindex org-table-export-default-format
|
||
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 @code{org-table-export-default-format}. You may also
|
||
use properties @samp{TABLE_EXPORT_FILE} and @samp{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 @ref{Translator functions}, for a detailed
|
||
description.
|
||
@end table
|
||
|
||
@node Column Width and Alignment
|
||
@section Column Width and Alignment
|
||
|
||
@cindex narrow columns in tables
|
||
@cindex alignment in tables
|
||
|
||
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.
|
||
|
||
@vindex org-table-automatic-realign
|
||
Editing a field may modify alignment of the table. Moving
|
||
a contiguous row or column---i.e., using @kbd{@key{TAB}} or
|
||
@kbd{@key{RET}}---automatically re-aligns it. If you want to disable
|
||
this behavior, set @code{org-table-automatic-realign} to @code{nil}. In any
|
||
case, you can always align manually a table:
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-c} (@code{org-table-align})
|
||
@kindex C-c C-c
|
||
@findex org-table-align
|
||
Align the current table.
|
||
@end table
|
||
|
||
@noindent
|
||
@vindex org-startup-align-all-tables
|
||
Setting the option @code{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:
|
||
|
||
@example
|
||
#+STARTUP: align
|
||
#+STARTUP: noalign
|
||
@end example
|
||
|
||
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.
|
||
|
||
@example
|
||
|---+---------------------+--------| |---+-------…|…|
|
||
| | <6> | | | | <6> …|…|
|
||
| 1 | one | some | ----\ | 1 | one …|…|
|
||
| 2 | two | boring | ----/ | 2 | two …|…|
|
||
| 3 | This is a long text | column | | 3 | This i…|…|
|
||
|---+---------------------+--------| |---+-------…|…|
|
||
@end example
|
||
|
||
To set the width of a column, one field anywhere in the column may
|
||
contain just the string @samp{<N>} where @var{N} specifies the width
|
||
as a number of characters. You control displayed width of columns
|
||
with the following tools:
|
||
|
||
@table @asis
|
||
@item @kbd{C-c @key{TAB}} (@code{org-table-toggle-column-width})
|
||
@kindex C-c TAB
|
||
@findex 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.
|
||
|
||
@item @kbd{C-u C-c @key{TAB}} (@code{org-table-shrink})
|
||
@kindex C-u C-c TAB
|
||
@findex org-table-shrink
|
||
Shrink all columns with a column width. Expand the others.
|
||
|
||
@item @kbd{C-u C-u C-c @key{TAB}} (@code{org-table-expand})
|
||
@kindex C-u C-u C-c TAB
|
||
@findex org-table-expand
|
||
Expand all columns.
|
||
@end table
|
||
|
||
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, @kbd{C-h .} (@code{display-local-help}) reveals them,
|
||
too. For convenience, any change near the shrunk part of a column
|
||
expands it.
|
||
|
||
@vindex org-startup-shrink-all-tables
|
||
Setting the option @code{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:
|
||
|
||
@example
|
||
#+STARTUP: shrink
|
||
@end example
|
||
|
||
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 @samp{<r>}, @samp{<c>} or @samp{<l>} in a similar fashion. You may also combine
|
||
alignment and field width like this: @samp{<r10>}.
|
||
|
||
Lines which only contain these formatting cookies are removed
|
||
automatically upon exporting the document.
|
||
|
||
@node Column Groups
|
||
@section Column Groups
|
||
|
||
@cindex grouping columns in tables
|
||
|
||
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 @samp{/}. The further fields can either contain
|
||
@samp{<} to indicate that this column should start a group, @samp{>} to indicate
|
||
the end of a column, or @samp{<>} (no space between @samp{<} and @samp{>}) to make
|
||
a column a group of its own. Upon export, boundaries between column
|
||
groups are marked with vertical lines. Here is an example:
|
||
|
||
@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)))
|
||
@end example
|
||
|
||
It is also sufficient to just insert the column group starters after
|
||
every vertical line you would like to have:
|
||
|
||
@example
|
||
| N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
|
||
|---+-----+-----+-----+---------+------------|
|
||
| / | < | | | < | |
|
||
@end example
|
||
|
||
@node Orgtbl Mode
|
||
@section The Orgtbl Minor Mode
|
||
|
||
@cindex Orgtbl mode
|
||
@cindex minor mode for tables
|
||
|
||
@findex orgtbl-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 @kbd{M-x orgtbl-mode}. To turn it on by default, for
|
||
example in Message mode, use
|
||
|
||
@lisp
|
||
(add-hook 'message-mode-hook 'turn-on-orgtbl)
|
||
@end lisp
|
||
|
||
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
|
||
@ref{Tables in Arbitrary Syntax}.
|
||
|
||
@node The spreadsheet
|
||
@section The spreadsheet
|
||
|
||
@cindex calculations, in tables
|
||
@cindex spreadsheet capabilities
|
||
@cindex Calc package
|
||
|
||
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 @emph{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 the 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...
|
||
@end menu
|
||
|
||
@node References
|
||
@subsection References
|
||
|
||
@cindex 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 @kbd{C-c ?} in
|
||
that field, or press @kbd{C-c @}} to toggle the display of a grid.
|
||
|
||
@anchor{Field references}
|
||
@subsubheading Field references
|
||
|
||
@cindex field references
|
||
@cindex references, to fields
|
||
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 @samp{B3}, meaning the second field in the
|
||
third row. However, Org prefers to use another, more general
|
||
representation that looks like this:@footnote{Org understands references typed by the user as @samp{B4}, but it
|
||
does not use this syntax when offering a formula for editing. You can
|
||
customize this behavior using the variable
|
||
@code{org-table-use-standard-references}.}
|
||
|
||
@example
|
||
@@ROW$COLUMN
|
||
@end example
|
||
|
||
Column specifications can be absolute like @samp{$1}, @samp{$2}, @dots{}, @samp{$N}, or
|
||
relative to the current column, i.e., the column of the field which is
|
||
being computed, like @samp{$+1} or @samp{$-2}. @samp{$<} and @samp{$>} are immutable
|
||
references to the first and last column, respectively, and you can use
|
||
@samp{$>>>} 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 @samp{@@1}, @samp{@@2}, @dots{}, @samp{@@N}, and row numbers relative to the
|
||
current row like @samp{@@+3} or @samp{@@-1}. @samp{@@<} and @samp{@@>} are immutable
|
||
references the first and last row in the table, respectively. You may
|
||
also specify the row relative to one of the hlines: @samp{@@I} refers to the
|
||
first hline, @samp{@@II} to the second, etc. @samp{@@-I} refers to the first such
|
||
line above the current line, @samp{@@+I} to the first such line below the
|
||
current line. You can also write @samp{@@III+2} which is the second data
|
||
line after the third hline in the table.
|
||
|
||
@samp{@@0} and @samp{$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 @emph{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 @emph{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:
|
||
|
||
@multitable @columnfractions 0.2 0.8
|
||
@item @samp{@@2$3}
|
||
@tab 2nd row, 3rd column (same as @samp{C2})
|
||
@item @samp{$5}
|
||
@tab column 5 in the current row (same as @samp{E&})
|
||
@item @samp{@@2}
|
||
@tab current column, row 2
|
||
@item @samp{@@-1$-3}
|
||
@tab field one row up, three columns to the left
|
||
@item @samp{@@-I$2}
|
||
@tab field just under hline above current row, column 2
|
||
@item @samp{@@>$5}
|
||
@tab field in the last row, in column 5
|
||
@end multitable
|
||
|
||
@anchor{Range references}
|
||
@subsubheading Range references
|
||
|
||
@cindex range references
|
||
@cindex references, to ranges
|
||
You may reference a rectangular range of fields by specifying two
|
||
field references connected by two dots @samp{..}. If both fields are in
|
||
the current row, you may simply use @samp{$2..$7}, but if at least one
|
||
field is in a different row, you need to use the general @samp{@@ROW$COLUMN}
|
||
format at least for the first field, i.e., the reference must start
|
||
with @samp{@@} in order to be interpreted correctly. Examples:
|
||
|
||
@multitable @columnfractions 0.2 0.8
|
||
@item @samp{$1..$3}
|
||
@tab first three fields in the current row
|
||
@item @samp{$P..$Q}
|
||
@tab range, using column names (see @ref{Advanced features})
|
||
@item @samp{$<<<..$>>}
|
||
@tab start in third column, continue to the last but one
|
||
@item @samp{@@2$1..@@4$3}
|
||
@tab six fields between these two fields (same as @samp{A2..C4})
|
||
@item @samp{@@-1$-2..@@-1}
|
||
@tab 3 fields in the row above, starting from 2 columns on the left
|
||
@item @samp{@@I..II}
|
||
@tab between first and second hline, short for @samp{@@I..@@II}
|
||
@end multitable
|
||
|
||
@noindent
|
||
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 @samp{E}, @samp{N} and examples, see @ref{Formula syntax for Calc}.
|
||
|
||
@anchor{Field coordinates in formulas}
|
||
@subsubheading Field coordinates in formulas
|
||
|
||
@cindex field coordinates
|
||
@cindex coordinates, of field
|
||
@cindex row, of field coordinates
|
||
@cindex column, of field coordinates
|
||
@vindex org-table-current-column
|
||
@vindex org-table-current-dline
|
||
One of the very first actions during evaluation of Calc formulas and
|
||
Lisp formulas is to substitute @samp{@@#} and @samp{$#} 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 @code{org-table-current-dline}
|
||
and @code{org-table-current-column}. Examples:
|
||
|
||
@table @asis
|
||
@item @samp{if(@@# % 2, $#, string(""))}
|
||
Insert column number on odd rows, set field to empty on even
|
||
rows.
|
||
|
||
@item @samp{$2 = '(identity remote(FOO, @@@@#$1))}
|
||
Copy text or values of each row of column 1 of the table named
|
||
@var{FOO} into column 2 of the current table.
|
||
|
||
@item @samp{@@3 = 2 * remote(FOO, @@@@1$$#)}
|
||
Insert the doubled value of each column of row 1 of the table
|
||
named @var{FOO} into row 3 of the current table.
|
||
@end table
|
||
|
||
@noindent
|
||
For the second and third examples, table @var{FOO} must have at
|
||
least as many rows or columns as the current table. Note that this is
|
||
inefficient@footnote{The computation time scales as O(N^2) because table
|
||
@var{FOO} is parsed for each field to be copied.} for large number of rows.
|
||
|
||
@anchor{Named references}
|
||
@subsubheading Named references
|
||
|
||
@cindex named references
|
||
@cindex references, named
|
||
@cindex name, of column or field
|
||
@cindex constants, in calculations
|
||
@cindex @samp{CONSTANTS}, keyword
|
||
@vindex org-table-formula-constants
|
||
|
||
@samp{$name} is interpreted as the name of a column, parameter or constant.
|
||
Constants are defined globally through the variable
|
||
@code{org-table-formula-constants}, and locally---for the file---through
|
||
a line like this example:
|
||
|
||
@example
|
||
#+CONSTANTS: c=299792458. pi=3.14 eps=2.4e-6
|
||
@end example
|
||
|
||
@noindent
|
||
@vindex constants-unit-system
|
||
@pindex constants.el
|
||
Also, properties (see @ref{Properties and Columns}) can be used as
|
||
constants in table formulas: for a property @samp{Xyz} use the name
|
||
@samp{$PROP_Xyz}, and the property will be searched in the current outline
|
||
entry and in the hierarchy above it. If you have the @samp{constants.el}
|
||
package, it will also be used to resolve constants, including natural
|
||
constants like @samp{$h} for Planck's constant, and units like @samp{$km} for
|
||
kilometers@footnote{The file @samp{constants.el} can supply the values of constants in
|
||
two different unit systems, @samp{SI} and @samp{cgs}. Which one is used depends
|
||
on the value of the variable @code{constants-unit-system}. You can use the
|
||
@samp{STARTUP} options @samp{constSI} and @samp{constcgs} to set this value for the
|
||
current buffer.}. Column names and parameters can be specified in
|
||
special table lines. These are described below, see @ref{Advanced features}. All names must start with a letter, and further consist
|
||
of letters and numbers.
|
||
|
||
@anchor{Remote references}
|
||
@subsubheading Remote references
|
||
|
||
@cindex remote references
|
||
@cindex references, remote
|
||
@cindex references, to a different table
|
||
@cindex name, of column or field
|
||
@cindex @samp{NAME}, keyword
|
||
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
|
||
|
||
@example
|
||
remote(NAME,REF)
|
||
@end example
|
||
|
||
@noindent
|
||
where @var{NAME} can be the name of a table in the current file
|
||
as set by a @samp{#+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. @var{REF} is an absolute field or
|
||
range reference as described above for example @samp{@@3$3} or @samp{$somename},
|
||
valid in the referenced table.
|
||
|
||
@cindex table indirection
|
||
When @var{NAME} has the format @samp{@@ROW$COLUMN}, it is substituted
|
||
with the name or ID found in this field of the current table. For
|
||
example @samp{remote($1, @@@@>$2)} @result{} @samp{remote(year_2013, @@@@>$1)}. The format
|
||
@samp{B3} is not supported because it can not be distinguished from a plain
|
||
table name or ID.
|
||
|
||
@node Formula syntax for Calc
|
||
@subsection Formula syntax for Calc
|
||
|
||
@cindex formula syntax, Calc
|
||
@cindex syntax, of formulas
|
||
|
||
A formula can be any algebraic expression understood by the Emacs Calc
|
||
package. Note that Calc has the non-standard convention that @samp{/} has
|
||
lower precedence than @samp{*}, so that @samp{a/b*c} is interpreted as
|
||
@samp{(a/(b*c))}. Before evaluation by @code{calc-eval} (see @ref{Calling Calc from Your Programs,Calling Calc from
|
||
Your Lisp Programs,,calc,}), variable substitution takes place according to
|
||
the rules described above.
|
||
|
||
@cindex vectors, in table calculations
|
||
The range vectors can be directly fed into the Calc vector functions
|
||
like @code{vmean} and @code{vsum}.
|
||
|
||
@cindex format specifier, in spreadsheet
|
||
@cindex mode, for Calc
|
||
@vindex org-calc-default-modes
|
||
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 @code{(float 8)} to keep
|
||
tables compact. The default settings can be configured using the
|
||
variable @code{org-calc-default-modes}.
|
||
|
||
@table @asis
|
||
@item @samp{p20}
|
||
Set the internal Calc calculation precision to 20 digits.
|
||
|
||
@item @samp{n3}, @samp{s3}, @samp{e2}, @samp{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.
|
||
|
||
@item @samp{D}, @samp{R}
|
||
Degree and radian angle modes of Calc.
|
||
|
||
@item @samp{F}, @samp{S}
|
||
Fraction and symbolic modes of Calc.
|
||
|
||
@item @samp{T}, @samp{t}, @samp{U}
|
||
Duration computations in Calc or Lisp, @ref{Durations and time values}.
|
||
|
||
@item @samp{E}
|
||
If and how to consider empty fields. Without @samp{E} empty fields in
|
||
range references are suppressed so that the Calc vector or Lisp
|
||
list contains only the non-empty fields. With @samp{E} the empty
|
||
fields are kept. For empty fields in ranges or empty field
|
||
references the value @samp{nan} (not a number) is used in Calc
|
||
formulas and the empty string is used for Lisp formulas. Add @samp{N}
|
||
to use 0 instead for both formula types. For the value of
|
||
a field the mode @samp{N} has higher precedence than @samp{E}.
|
||
|
||
@item @samp{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 @samp{N}.
|
||
|
||
@item @samp{L}
|
||
Literal, for Lisp formulas only. See the next section.
|
||
@end table
|
||
|
||
@noindent
|
||
Unless you use large integer numbers or high-precision calculation and
|
||
display for floating point numbers you may alternatively provide
|
||
a @code{printf} format specifier to reformat the Calc result after it has
|
||
been passed back to Org instead of letting Calc already do the
|
||
formatting@footnote{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.}. A few examples:
|
||
|
||
@multitable {aaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
|
||
@item @samp{$1+$2}
|
||
@tab Sum of first and second field
|
||
@item @samp{$1+$2;%.2f}
|
||
@tab Same, format result to two decimals
|
||
@item @samp{exp($2)+exp($1)}
|
||
@tab Math functions can be used
|
||
@item @samp{$0;%.1f}
|
||
@tab Reformat current cell to 1 decimal
|
||
@item @samp{($3-32)*5/9}
|
||
@tab Degrees F @arrow{} C conversion
|
||
@item @samp{$c/$1/$cm}
|
||
@tab Hz @arrow{} cm conversion, using @samp{constants.el}
|
||
@item @samp{tan($1);Dp3s1}
|
||
@tab Compute in degrees, precision 3, display SCI 1
|
||
@item @samp{sin($1);Dp3%.1e}
|
||
@tab Same, but use @code{printf} specifier for display
|
||
@item @samp{vmean($2..$7)}
|
||
@tab Compute column range mean, using vector function
|
||
@item @samp{vmean($2..$7);EN}
|
||
@tab Same, but treat empty fields as 0
|
||
@item @samp{taylor($3,x=7,2)}
|
||
@tab Taylor series of $3, at x=7, second degree
|
||
@end multitable
|
||
|
||
Calc also contains a complete set of logical operations (see @ref{Logical Operations,Logical
|
||
Operations,,calc,}). For example
|
||
|
||
@table @asis
|
||
@item @samp{if($1 < 20, teen, string(""))}
|
||
@samp{"teen"} if age @samp{$1} is less than 20, else the Org table result
|
||
field is set to empty with the empty string.
|
||
|
||
@item @samp{if("$1" =} ``nan'' || ``$2'' @samp{= "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. @samp{E}
|
||
is required to not convert empty fields to 0. @samp{f-1} is an
|
||
optional Calc format string similar to @samp{%.1f} but leaves empty
|
||
results empty.
|
||
|
||
@item @samp{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 @samp{nan} which lets
|
||
@samp{vmean} result in @samp{nan}. Then @samp{typeof =} 12= detects the @samp{nan}
|
||
from @code{vmean} and the Org table result field is set to empty. Use
|
||
this when the sample set is expected to never have missing
|
||
values.
|
||
|
||
@item @samp{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.
|
||
|
||
@item @samp{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.
|
||
@end table
|
||
|
||
You can add your own Calc functions defined in Emacs Lisp with
|
||
@code{defmath} and use them in formula syntax for Calc.
|
||
|
||
@node Formula syntax for Lisp
|
||
@subsection Emacs Lisp forms as formulas
|
||
|
||
@cindex Lisp forms, as table 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.
|
||
|
||
If a formula starts with a single-quote followed by an opening
|
||
parenthesis, then it is evaluated as a Lisp form. The evaluation
|
||
should return either a string or a number. Just as with Calc
|
||
formulas, you can specify modes and a @code{printf} format after
|
||
a semicolon.
|
||
|
||
With Emacs Lisp forms, you need to be conscious about the way field
|
||
references are interpolated into the form. By default, a reference is
|
||
interpolated as a Lisp string (in double-quotes) containing the field.
|
||
If you provide the @samp{N} mode switch, all referenced elements are
|
||
numbers---non-number fields will be zero---and interpolated as Lisp
|
||
numbers, without quotes. If you provide the @samp{L} flag, all fields are
|
||
interpolated literally, without quotes. I.e., if you want a reference
|
||
to be interpreted as a string by the Lisp form, enclose the reference
|
||
operator itself in double-quotes, like @samp{"$3"}. Ranges are inserted as
|
||
space-separated fields, so you can embed them in list or vector
|
||
syntax.
|
||
|
||
Here are a few examples---note how the @samp{N} mode is used when we do
|
||
computations in Lisp:
|
||
|
||
@table @asis
|
||
@item @samp{'(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2))}
|
||
Swap the first two characters of the content of column 1.
|
||
|
||
@item @samp{'(+ $1 $2);N}
|
||
Add columns 1 and 2, equivalent to Calc's @samp{$1+$2}.
|
||
|
||
@item @samp{'(apply '+ '($1..$4));N}
|
||
Compute the sum of columns 1 to 4, like Calc's @samp{vsum($1..$4)}.
|
||
@end table
|
||
|
||
@node Durations and time values
|
||
@subsection Durations and time values
|
||
|
||
@cindex Duration, computing
|
||
@cindex Time, computing
|
||
@vindex org-table-duration-custom-format
|
||
|
||
If you want to compute time values use the @samp{T}, @samp{t}, or @samp{U} flag,
|
||
either in Calc formulas or Elisp formulas:
|
||
|
||
@example
|
||
| 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
|
||
@end example
|
||
|
||
Input duration values must be of the form @samp{HH:MM[:SS]}, where seconds
|
||
are optional. With the @samp{T} flag, computed durations are displayed as
|
||
@samp{HH:MM:SS} (see the first formula above). With the @samp{U} flag, seconds
|
||
are omitted so that the result is only @samp{HH:MM} (see second formula
|
||
above). Zero-padding of the hours field depends upon the value of the
|
||
variable @code{org-table-duration-hour-zero-padding}.
|
||
|
||
With the @samp{t} flag, computed durations are displayed according to the
|
||
value of the option @code{org-table-duration-custom-format}, which defaults
|
||
to @code{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.
|
||
|
||
@node Field and range formulas
|
||
@subsection Field and range formulas
|
||
|
||
@cindex field formula
|
||
@cindex range formula
|
||
@cindex formula, for individual table field
|
||
@cindex formula, for range of fields
|
||
|
||
To assign a formula to a particular field, type it directly into the
|
||
field, preceded by @samp{:=}, for example @samp{vsum(@@II..III)}. When you press
|
||
@kbd{@key{TAB}} or @kbd{@key{RET}} or @kbd{C-c C-c} with the cursor
|
||
still in the field, the formula is stored as the formula for this
|
||
field, evaluated, and the current field is replaced with the result.
|
||
|
||
@cindex @samp{TBLFM}, keyword
|
||
Formulas are stored in a special @samp{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 @samp{@@3$4=$1+$2}.
|
||
When inserting/deleting/swapping column and rows with the appropriate
|
||
commands, @emph{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 @samp{@@<}, @samp{@@>}, @samp{$<}, @samp{$>}), or at
|
||
hlines using the @samp{@@I} notation. Automatic adaptation of field
|
||
references does of course not happen if you edit the table structure
|
||
with normal editing commands---then you must fix the equations
|
||
yourself.
|
||
|
||
Instead of typing an equation into the field, you may also use the
|
||
following command
|
||
|
||
@table @asis
|
||
@item @kbd{C-u C-c =} (@code{org-table-eval-formula})
|
||
@kindex C-u C-c =
|
||
@findex org-table-eval-formula
|
||
Install a new formula for the current field. The command prompts
|
||
for a formula with default taken from the @samp{TBLFM} keyword,
|
||
applies it to the current field, and stores it.
|
||
@end table
|
||
|
||
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 @ref{Editing and debugging formulas}) or edit the
|
||
@samp{TBLFM} keyword directly.
|
||
|
||
@table @asis
|
||
@item @samp{$2=}
|
||
Column formula, valid for the entire column. This is so common
|
||
that Org treats these formulas in a special way, see @ref{Column formulas}.
|
||
|
||
@item @code{@@3=}
|
||
Row formula, applies to all fields in the specified row. @samp{@@>=}
|
||
means the last row.
|
||
|
||
@item @samp{@@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.
|
||
|
||
@item @samp{$NAME=}
|
||
Named field, see @ref{Advanced features}.
|
||
@end table
|
||
|
||
@node Column formulas
|
||
@subsection Column formulas
|
||
|
||
@cindex column formula
|
||
@cindex formula, for table column
|
||
|
||
When you assign a formula to a simple column reference like @samp{$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 @emph{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 @samp{=$1+$2}. When you press
|
||
@kbd{@key{TAB}} or @kbd{@key{RET}} or @kbd{C-c C-c} with the cursor
|
||
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 @samp{=}, the previously stored formula
|
||
for this column is used. For each column, Org only remembers the most
|
||
recently used formula. In the @samp{TBLFM} keyword, column formulas look
|
||
like @samp{$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 @samp{$>}.
|
||
|
||
Instead of typing an equation into the field, you may also use the
|
||
following command:
|
||
|
||
@table @asis
|
||
@item @kbd{C-c =} (@code{org-table-eval-formula})
|
||
@kindex C-c =
|
||
@findex 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 @samp{TBLFM} keyword, applies
|
||
it to the current field and stores it. With a numeric prefix
|
||
argument, e.g., @kbd{C-5 C-c =}, the command applies it to
|
||
that many consecutive fields in the current column.
|
||
@end table
|
||
|
||
@node Lookup functions
|
||
@subsection Lookup functions
|
||
|
||
@cindex lookup functions in tables
|
||
@cindex table lookup functions
|
||
|
||
Org has three predefined Emacs Lisp functions for lookups in tables.
|
||
|
||
@table @asis
|
||
@item @code{(org-lookup-first VAL S-LIST R-LIST &optional PREDICATE)}
|
||
@findex org-lookup-first
|
||
Searches for the first element @var{S} in list
|
||
@var{S-LIST} for which
|
||
@lisp
|
||
(PREDICATE VAL S)
|
||
@end lisp
|
||
is non-@code{nil}; returns the value from the corresponding position
|
||
in list @var{R-LIST}. The default @var{PREDICATE} is
|
||
@code{equal}. Note that the parameters @var{VAL} and
|
||
@var{S} are passed to @var{PREDICATE} in the same order
|
||
as the corresponding parameters are in the call to
|
||
@code{org-lookup-first}, where @var{VAL} precedes
|
||
@var{S-LIST}. If @var{R-LIST} is @code{nil}, the matching
|
||
element @var{S} of @var{S-LIST} is returned.
|
||
|
||
@item @code{(org-lookup-last VAL S-LIST R-LIST &optional PREDICATE)}
|
||
@findex org-lookup-last
|
||
Similar to @code{org-lookup-first} above, but searches for the @emph{last}
|
||
element for which @var{PREDICATE} is non-@code{nil}.
|
||
|
||
@item @code{(org-lookup-all VAL S-LIST R-LIST &optional PREDICATE)}
|
||
@findex org-lookup-all
|
||
Similar to @code{org-lookup-first}, but searches for @emph{all} elements
|
||
for which @var{PREDICATE} is non-@code{nil}, and returns @emph{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.
|
||
@end table
|
||
|
||
If the ranges used in these functions contain empty fields, the @samp{E}
|
||
mode for the formula should usually be specified: otherwise empty
|
||
fields are not included in @var{S-LIST} and/or @var{R-LIST}
|
||
which can, for example, result in an incorrect mapping from an element
|
||
of @var{S-LIST} to the corresponding element of
|
||
@var{R-LIST}.
|
||
|
||
These three functions can be used to implement associative arrays,
|
||
count matching cells, rank results, group data, etc. For practical
|
||
examples see @uref{https://orgmode.org/worg/org-tutorials/org-lookups.html, this tutorial on Worg}.
|
||
|
||
@node Editing and debugging formulas
|
||
@subsection Editing and debugging formulas
|
||
|
||
@cindex formula editing
|
||
@cindex editing, of table formulas
|
||
|
||
@vindex org-table-use-standard-references
|
||
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 @samp{B3} or @samp{D&}) if possible. If
|
||
you prefer to only work with the internal format (like @samp{@@3$2} or
|
||
@samp{$4}), configure the variable @code{org-table-use-standard-references}.
|
||
|
||
@table @asis
|
||
@item @kbd{C-c =} or @kbd{C-u C-c =} (@code{org-table-eval-formula})
|
||
@kindex C-c =
|
||
@kindex C-u C-c =
|
||
@findex org-table-eval-formula
|
||
Edit the formula associated with the current column/field in the
|
||
minibuffer. See @ref{Column formulas}, and @ref{Field and range formulas}.
|
||
|
||
@item @kbd{C-u C-u C-c =} (@code{org-table-eval-formula})
|
||
@kindex C-u C-u C-c =
|
||
@findex 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 @kbd{C-c ?}.
|
||
|
||
@item @kbd{C-c ?} (@code{org-table-field-info})
|
||
@kindex C-c ?
|
||
@findex org-table-field-info
|
||
While editing a formula in a table field, highlight the field(s)
|
||
referenced by the reference at the cursor position in the
|
||
formula.
|
||
|
||
@item @kbd{C-c @}} (@code{org-table-toggle-coordinate-overlays})
|
||
@kindex C-c @}
|
||
@findex 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 @kbd{C-c C-c}.
|
||
|
||
@item @kbd{C-c @{} (@code{org-table-toggle-formula-debugger})
|
||
@kindex C-c @{
|
||
@findex org-table-toggle-formula-debugger
|
||
Toggle the formula debugger on and off. See below.
|
||
|
||
@item @kbd{C-c '} (@code{org-table-edit-formulas})
|
||
@kindex C-c '
|
||
@findex 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, the cursor in the formula editor
|
||
marks it. While inside the special buffer, Org automatically
|
||
highlights any field or range reference at the cursor position.
|
||
You may edit, remove and add formulas, and use the following
|
||
commands:
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-c} or @kbd{C-x C-s} (@code{org-table-fedit-finish})
|
||
@kindex C-x C-s
|
||
@kindex C-c C-c
|
||
@findex org-table-fedit-finish
|
||
Exit the formula editor and store the modified formulas. With
|
||
@kbd{C-u} prefix, also apply the new formulas to the
|
||
entire table.
|
||
|
||
@item @kbd{C-c C-q} (@code{org-table-fedit-abort})
|
||
@kindex C-c C-q
|
||
@findex org-table-fedit-abort
|
||
Exit the formula editor without installing changes.
|
||
|
||
@item @kbd{C-c C-r} (@code{org-table-fedit-toggle-ref-type})
|
||
@kindex C-c C-r
|
||
@findex org-table-fedit-toggle-ref-type
|
||
Toggle all references in the formula editor between standard
|
||
(like @samp{B3}) and internal (like @samp{@@3$2}).
|
||
|
||
@item @kbd{@key{TAB}} (@code{org-table-fedit-lisp-indent})
|
||
@kindex TAB
|
||
@findex 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 @kbd{@key{TAB}} collapses the formula
|
||
back again. In the open formula, @kbd{@key{TAB}} re-indents
|
||
just like in Emacs Lisp mode.
|
||
|
||
@item @kbd{M-@key{TAB}} (@code{lisp-complete-symbol})
|
||
@kindex M-TAB
|
||
@findex lisp-complete-symbol
|
||
Complete Lisp symbols, just like in Emacs Lisp mode.
|
||
|
||
@item @kbd{S-@key{UP}}, @kbd{S-@key{DOWN}}, @kbd{S-@key{LEFT}}, @kbd{S-@key{RIGHT}}
|
||
@kindex S-UP
|
||
@kindex S-DOWN
|
||
@kindex S-LEFT
|
||
@kindex S-RIGHT
|
||
@findex org-table-fedit-ref-up
|
||
@findex org-table-fedit-ref-down
|
||
@findex org-table-fedit-ref-left
|
||
@findex org-table-fedit-ref-right
|
||
Shift the reference at point. For example, if the reference
|
||
is @samp{B3} and you press @kbd{S-@key{RIGHT}}, it becomes @samp{C3}.
|
||
This also works for relative references and for hline
|
||
references.
|
||
|
||
@item @kbd{M-S-@key{UP}} (@code{org-table-fedit-line-up})
|
||
@kindex M-S-UP
|
||
@findex org-table-fedit-line-up
|
||
Move the test line for column formulas up in the Org buffer.
|
||
|
||
@item @kbd{M-S-@key{DOWN}} (@code{org-table-fedit-line-down})
|
||
@kindex M-S-DOWN
|
||
@findex org-table-fedit-line-down
|
||
Move the test line for column formulas down in the Org buffer.
|
||
|
||
@item @kbd{M-@key{UP}} (@code{org-table-fedit-scroll-up})
|
||
@kindex M-UP
|
||
@findex org-table-fedit-scroll-up
|
||
Scroll up the window displaying the table.
|
||
|
||
@item @kbd{M-@key{DOWN}} (@code{org-table-fedit-scroll-down})
|
||
@kindex M-DOWN
|
||
@findex org-table-fedit-scroll-down
|
||
Scroll down the window displaying the table.
|
||
|
||
@item @kbd{C-c @}}
|
||
@kindex C-c @}
|
||
@findex org-table-toggle-coordinate-overlays
|
||
Turn the coordinate grid in the table on and off.
|
||
@end table
|
||
@end table
|
||
|
||
Making a table field blank does not remove the formula associated with
|
||
the field, because that is stored in a different line---the @samp{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 @samp{TBLFM} keyword.
|
||
|
||
@kindex C-c C-c
|
||
You may edit the @samp{TBLFM} keyword directly and re-apply the changed
|
||
equations with @kbd{C-c C-c} in that line or with the normal
|
||
recalculation commands in the table.
|
||
|
||
@anchor{Using multiple @samp{TBLFM} lines}
|
||
@subsubheading Using multiple @samp{TBLFM} lines
|
||
|
||
@cindex multiple formula lines
|
||
@cindex @samp{TBLFM} keywords, multiple
|
||
@cindex @samp{TBLFM}, switching
|
||
|
||
@kindex C-c C-c
|
||
You may apply the formula temporarily. This is useful when you switch
|
||
the formula. Place multiple @samp{TBLFM} keywords right after the table,
|
||
and then press @kbd{C-c C-c} on the formula to apply. Here is an
|
||
example:
|
||
|
||
@example
|
||
| x | y |
|
||
|---+---|
|
||
| 1 | |
|
||
| 2 | |
|
||
#+TBLFM: $2=$1*1
|
||
#+TBLFM: $2=$1*2
|
||
@end example
|
||
|
||
@noindent
|
||
Pressing @kbd{C-c C-c} in the line of @samp{#+TBLFM: $2=$1*2} yields:
|
||
|
||
@example
|
||
| x | y |
|
||
|---+---|
|
||
| 1 | 2 |
|
||
| 2 | 4 |
|
||
#+TBLFM: $2=$1*1
|
||
#+TBLFM: $2=$1*2
|
||
@end example
|
||
|
||
@noindent
|
||
Note: If you recalculate this table, with @kbd{C-u C-c *}, for
|
||
example, you get the following result of applying only the first
|
||
@samp{TBLFM} keyword.
|
||
|
||
@example
|
||
| x | y |
|
||
|---+---|
|
||
| 1 | 1 |
|
||
| 2 | 2 |
|
||
#+TBLFM: $2=$1*1
|
||
#+TBLFM: $2=$1*2
|
||
@end example
|
||
|
||
@anchor{Debugging formulas}
|
||
@subsubheading Debugging formulas
|
||
|
||
@cindex formula debugging
|
||
@cindex debugging, of table formulas
|
||
|
||
When the evaluation of a formula leads to an error, the field content
|
||
becomes the string @samp{#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 @kbd{C-u C-u C-c = @key{RET}} in
|
||
a field. Detailed information are displayed.
|
||
|
||
@node Updating the table
|
||
@subsection Updating the table
|
||
|
||
@cindex recomputing table fields
|
||
@cindex updating, 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 @ref{Advanced features}.
|
||
|
||
In order to recalculate a line of a table or the entire table, use the
|
||
following commands:
|
||
|
||
@table @asis
|
||
@item @kbd{C-c *} (@code{org-table-recalculate})
|
||
@kindex C-c *
|
||
@findex 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.
|
||
|
||
@item @kbd{C-u C-c *} or @kbd{C-u C-c C-c}
|
||
@kindex C-u C-c *
|
||
@kindex 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.
|
||
|
||
@item @kbd{C-u C-u C-c *} or @kbd{C-u C-u C-c C-c} (@code{org-table-iterate})
|
||
@kindex C-u C-u C-c *
|
||
@kindex C-u C-u C-c C-c
|
||
@findex 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 @emph{later} in the
|
||
calculation sequence.
|
||
|
||
@item @kbd{M-x org-table-recalculate-buffer-tables}
|
||
@findex org-table-recalculate-buffer-tables
|
||
Recompute all tables in the current buffer.
|
||
|
||
@item @kbd{M-x org-table-iterate-buffer-tables}
|
||
@findex org-table-iterate-buffer-tables
|
||
Iterate all tables in the current buffer, in order to converge
|
||
table-to-table dependencies.
|
||
@end table
|
||
|
||
@node Advanced features
|
||
@subsection Advanced features
|
||
|
||
If you want the recalculation of fields to happen automatically, or if
|
||
you want to be able to assign @emph{names}@footnote{Such names must start with an alphabetic character and use
|
||
only alphanumeric/underscore characters.} to fields and columns,
|
||
you need to reserve the first column of the table for special marking
|
||
characters.
|
||
|
||
@table @asis
|
||
@item @kbd{C-#} (@code{org-table-rotate-recalc-marks})
|
||
@kindex C-#
|
||
@findex org-table-rotate-recalc-marks
|
||
Rotate the calculation mark in first column through the states
|
||
@samp{#}, @samp{*}, @samp{!}, @samp{$}. When there is an active region, change all
|
||
marks in the region.
|
||
@end table
|
||
|
||
Here is an example of a table that collects exam results of students
|
||
and makes use of these features:
|
||
|
||
@example
|
||
|---+---------+--------+--------+--------+-------+------|
|
||
| | 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
|
||
@end example
|
||
|
||
@noindent
|
||
@strong{Important}: please note that for these special tables, recalculating
|
||
the table with @kbd{C-u C-c *} only affects rows that are marked
|
||
@samp{#} or @samp{*}, and fields that have a formula assigned to the field
|
||
itself. The column formulas are not applied in rows with empty first
|
||
field.
|
||
|
||
@cindex marking characters, tables
|
||
The marking characters have the following meaning:
|
||
|
||
@table @asis
|
||
@item @samp{!}
|
||
The fields in this line define names for the columns, so that you
|
||
may refer to a column as @samp{$Tot} instead of @samp{$6}.
|
||
|
||
@item @samp{^}
|
||
This row defines names for the fields @emph{above} the row. With such
|
||
a definition, any formula in the table may use @samp{$m1} to refer to
|
||
the value @samp{10}. Also, if you assign a formula to a names field,
|
||
it is stored as @samp{$name = ...}.
|
||
|
||
@item @samp{_}
|
||
Similar to @samp{^}, but defines names for the fields in the row
|
||
@emph{below}.
|
||
|
||
@item @samp{$}
|
||
Fields in this row can define @emph{parameters} for formulas. For
|
||
example, if a field in a @samp{$} row contains @samp{max=50}, then formulas
|
||
in this table can refer to the value 50 using @samp{$max}. Parameters
|
||
work exactly like constants, only that they can be defined on
|
||
a per-table basis.
|
||
|
||
@item @samp{#}
|
||
Fields in this row are automatically recalculated when pressing
|
||
@kbd{@key{TAB}} or @kbd{@key{RET}} or @kbd{S-@key{TAB}} in this row.
|
||
Also, this row is selected for a global recalculation with
|
||
@kbd{C-u C-c *}. Unmarked lines are left alone by this
|
||
command.
|
||
|
||
@item @samp{*}
|
||
Selects this line for global recalculation with @kbd{C-u C-c *}, but not for automatic recalculation. Use this when
|
||
automatic recalculation slows down editing too much.
|
||
|
||
@item @samp{/}
|
||
Do not export this line. Useful for lines that contain the
|
||
narrowing @samp{<N>} markers or column group markers.
|
||
@end table
|
||
|
||
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.
|
||
|
||
@example
|
||
|---+-------------+---+-----+--------------------------------------|
|
||
| | 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
|
||
@end example
|
||
|
||
@node Org Plot
|
||
@section Org Plot
|
||
|
||
@cindex graph, in tables
|
||
@cindex plot tables using Gnuplot
|
||
|
||
Org Plot can produce graphs of information stored in Org tables,
|
||
either graphically or in ASCII art.
|
||
|
||
@anchor{Graphical plots using Gnuplot}
|
||
@subheading Graphical plots using Gnuplot
|
||
|
||
@cindex @samp{PLOT}, keyword
|
||
Org Plot can produce 2D and 3D graphs of information stored in Org
|
||
tables using @uref{http://www.gnuplot.info/, Gnuplot} and @uref{http://cars9.uchicago.edu/~ravel/software/gnuplot-mode.html, Gnuplot mode}. To see this in action, ensure
|
||
that you have both Gnuplot and Gnuplot mode installed on your system,
|
||
then call @kbd{C-c " g} or @kbd{M-x org-plot/gnuplot} on the
|
||
following table.
|
||
|
||
@example
|
||
#+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 |
|
||
@end example
|
||
|
||
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 @samp{PLOT} keyword
|
||
preceding a table. See below for a complete list of Org Plot options.
|
||
For more information and examples see the @uref{https://orgmode.org/worg/org-tutorials/org-plot.html, Org Plot tutorial}.
|
||
|
||
@anchor{Plot options}
|
||
@subsubheading Plot options
|
||
|
||
@table @asis
|
||
@item @samp{set}
|
||
Specify any Gnuplot option to be set when graphing.
|
||
|
||
@item @samp{title}
|
||
Specify the title of the plot.
|
||
|
||
@item @samp{ind}
|
||
Specify which column of the table to use as the @samp{x} axis.
|
||
|
||
@item @samp{deps}
|
||
Specify the columns to graph as a Lisp style list, surrounded by
|
||
parentheses and separated by spaces for example @samp{dep:(3 4)} to
|
||
graph the third and fourth columns. Defaults to graphing all
|
||
other columns aside from the @samp{ind} column.
|
||
|
||
@item @samp{type}
|
||
Specify whether the plot is @samp{2d}, @samp{3d}, or @samp{grid}.
|
||
|
||
@item @samp{with}
|
||
Specify a @samp{with} option to be inserted for every column being
|
||
plotted, e.g., @samp{lines}, @samp{points}, @samp{boxes}, @samp{impulses}. Defaults
|
||
to @samp{lines}.
|
||
|
||
@item @samp{file}
|
||
If you want to plot to a file, specify
|
||
@samp{"path/to/desired/output-file"}.
|
||
|
||
@item @samp{labels}
|
||
List of labels to be used for the @samp{deps}. Defaults to the column
|
||
headers if they exist.
|
||
|
||
@item @samp{line}
|
||
Specify an entire line to be inserted in the Gnuplot script.
|
||
|
||
@item @samp{map}
|
||
When plotting @samp{3d} or @samp{grid} types, set this to @samp{t} to graph
|
||
a flat mapping rather than a @samp{3d} slope.
|
||
|
||
@item @samp{timefmt}
|
||
Specify format of Org mode timestamps as they will be parsed by
|
||
Gnuplot. Defaults to @samp{%Y-%m-%d-%H:%M:%S}.
|
||
|
||
@item @samp{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 @samp{$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.
|
||
@end table
|
||
|
||
@anchor{ASCII bar plots}
|
||
@subheading ASCII bar plots
|
||
|
||
While the cursor is on a column, typing @kbd{C-c `` a} or
|
||
@kbd{M-x orgtbl-ascii-plot} create a new column containing an
|
||
ASCII-art bars 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 @kbd{C-u C-c *}.
|
||
|
||
@example
|
||
| 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)
|
||
@end example
|
||
|
||
The formula is an Elisp call.
|
||
|
||
@defun orgtbl-ascii-draw value min max &optional width
|
||
Draw an ASCII bar in a table.
|
||
|
||
@var{VALUE} is the value to plot.
|
||
|
||
@var{MIN} is the value displayed as an empty bar. @var{MAX}
|
||
is the value filling all the @var{WIDTH}. Sources values outside
|
||
this range are displayed as @samp{too small} or @samp{too large}.
|
||
|
||
@var{WIDTH} is the number of characters of the bar plot. It
|
||
defaults to @samp{12}.
|
||
@end defun
|
||
|
||
@node Hyperlinks
|
||
@chapter Hyperlinks
|
||
|
||
@cindex hyperlinks
|
||
|
||
Like HTML, Org provides 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.
|
||
@end menu
|
||
|
||
@node Link Format
|
||
@section Link Format
|
||
|
||
@cindex link format
|
||
@cindex format, of links
|
||
|
||
Org recognizes plain URL-like links and activate them as clickable
|
||
links. The general link format, however, looks like this:
|
||
|
||
@example
|
||
[[LINK][DESCRIPTION]]
|
||
@end example
|
||
|
||
@noindent
|
||
or alternatively
|
||
|
||
@example
|
||
[[LINK]]
|
||
@end example
|
||
|
||
@noindent
|
||
Once a link in the buffer is complete (all brackets present), Org
|
||
changes the display so that @samp{DESCRIPTION} is displayed instead of
|
||
@samp{[[LINK][DESCRIPTION]]} and @samp{LINK} is displayed instead of @samp{[[LINK]]}. Links are be
|
||
highlighted in the face @code{org-link}, which by default is an underlined
|
||
face. You can directly edit the visible part of a link. Note that
|
||
this can be either the LINK part, if there is no description, or the
|
||
@var{DESCRIPTION} part. To edit also the invisible
|
||
@var{LINK} part, use @kbd{C-c C-l} with the cursor on the
|
||
link.
|
||
|
||
If you place the cursor at the beginning or just behind the end of the
|
||
displayed text and press @kbd{@key{BS}}, you remove
|
||
the---invisible---bracket at that location. 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 @arrow{} Hyperlinks @arrow{}
|
||
Literal links.
|
||
|
||
@node Internal Links
|
||
@section Internal Links
|
||
|
||
@cindex internal links
|
||
@cindex links, internal
|
||
@cindex targets, for links
|
||
|
||
@cindex @samp{CUSTOM_ID}, property
|
||
If the link does not look like a URL, it is considered to be internal
|
||
in the current file. The most important case is a link like
|
||
@samp{[[#my-custom-id]]} which links to the entry with the @samp{CUSTOM_ID} property
|
||
@samp{my-custom-id}. You are responsible yourself to make sure these
|
||
custom IDs are unique in a file.
|
||
|
||
Links such as @samp{[[My Target]]} or @samp{[[My Target][Find my target]]} lead to a text search in
|
||
the current file.
|
||
|
||
The link can be followed with @kbd{C-c C-o} when the cursor is on
|
||
the link, or with a mouse click (see @ref{Handling Links}). Links to
|
||
custom IDs point to the corresponding headline. The preferred match
|
||
for a text link is a @emph{dedicated target}: the same string in double
|
||
angular brackets, like @samp{<<My Target>>}.
|
||
|
||
@cindex @samp{NAME}, keyword
|
||
If no dedicated target exists, the link tries to match the exact name
|
||
of an element within the buffer. Naming is done with the @samp{NAME}
|
||
keyword, which has to be put in the line before the element it refers
|
||
to, as in the following example
|
||
|
||
@example
|
||
#+NAME: My Target
|
||
| a | table |
|
||
|----+------------|
|
||
| of | four cells |
|
||
@end example
|
||
|
||
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@footnote{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 @kbd{M-@key{TAB}}. All headlines in the current
|
||
buffer are offered as completions.}.
|
||
|
||
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@footnote{When targeting a @samp{NAME} keyword, @samp{CAPTION} keyword is
|
||
mandatory in order to get proper numbering (see @ref{Images and Tables}).}. In the following excerpt from
|
||
an Org buffer
|
||
|
||
@example
|
||
1. one item
|
||
2. <<target>>another item
|
||
Here we refer to item [[target]].
|
||
@end example
|
||
|
||
@noindent
|
||
The last sentence will appear as @samp{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 @samp{target}.
|
||
|
||
Following a link pushes a mark onto Org's own mark ring. You can
|
||
return to the previous position with @kbd{C-c &}. Using this
|
||
command several times in direct succession goes back to positions
|
||
recorded earlier.
|
||
|
||
@node Radio Targets
|
||
@section Radio Targets
|
||
|
||
@cindex radio targets
|
||
@cindex targets, radio
|
||
@cindex links, 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 @samp{<<<My
|
||
Target>>>} causes each occurrence of @samp{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 @kbd{C-c C-c} with
|
||
the cursor on or at a target.
|
||
|
||
@node External Links
|
||
@section External Links
|
||
|
||
@cindex links, external
|
||
@cindex external links
|
||
@cindex Gnus links
|
||
@cindex BBDB links
|
||
@cindex irc links
|
||
@cindex URL links
|
||
@cindex file links
|
||
@cindex Rmail links
|
||
@cindex MH-E links
|
||
@cindex Usenet links
|
||
@cindex shell links
|
||
@cindex Info links
|
||
@cindex Elisp 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. The following list shows examples for each link type.
|
||
|
||
@multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
|
||
@item @samp{http://www.astro.uva.nl/=dominik}
|
||
@tab on the web
|
||
@item @samp{doi:10.1000/182}
|
||
@tab DOI for an electronic resource
|
||
@item @samp{file:/home/dominik/images/jupiter.jpg}
|
||
@tab file, absolute path
|
||
@item @samp{/home/dominik/images/jupiter.jpg}
|
||
@tab same as above
|
||
@item @samp{file:papers/last.pdf}
|
||
@tab file, relative path
|
||
@item @samp{./papers/last.pdf}
|
||
@tab same as above
|
||
@item @samp{file:/ssh:me@@some.where:papers/last.pdf}
|
||
@tab file, path on remote machine
|
||
@item @samp{/ssh:me@@some.where:papers/last.pdf}
|
||
@tab same as above
|
||
@item @samp{file:sometextfile::NNN}
|
||
@tab file, jump to line number
|
||
@item @samp{file:projects.org}
|
||
@tab another Org file
|
||
@item @samp{file:projects.org::some words}
|
||
@tab text search in Org file@footnote{The actual behavior of the search depends on the value of the
|
||
variable @code{org-link-search-must-match-exact-headline}. If its value is
|
||
@code{nil}, then a fuzzy text search is done. If it is @code{t}, then only the
|
||
exact headline is matched, ignoring spaces and statistic cookies. If
|
||
the value is @code{query-to-create}, then an exact headline is searched; if
|
||
it is not found, then the user is queried to create it.}
|
||
@item @samp{file:projects.org::*task title}
|
||
@tab heading search in Org file
|
||
@item @samp{file+sys:/path/to/file}
|
||
@tab open via OS, like double-click
|
||
@item @samp{file+emacs:/path/to/file}
|
||
@tab force opening by Emacs
|
||
@item @samp{docview:papers/last.pdf::NNN}
|
||
@tab open in doc-view mode at page
|
||
@item @samp{id:B7423F4D-2E8A-471B-8810-C40F074717E9}
|
||
@tab Link to heading by ID
|
||
@item @samp{news:comp.emacs}
|
||
@tab Usenet link
|
||
@item @samp{mailto:adent@@galaxy.net}
|
||
@tab Mail link
|
||
@item @samp{mhe:folder}
|
||
@tab MH-E folder link
|
||
@item @samp{mhe:folder#id}
|
||
@tab MH-E message link
|
||
@item @samp{rmail:folder}
|
||
@tab Rmail folder link
|
||
@item @samp{rmail:folder#id}
|
||
@tab Rmail message link
|
||
@item @samp{gnus:group}
|
||
@tab Gnus group link
|
||
@item @samp{gnus:group#id}
|
||
@tab Gnus article link
|
||
@item @samp{bbdb:R.*Stallman}
|
||
@tab BBDB link (with regexp)
|
||
@item @samp{irc:/irc.com/#emacs/bob}
|
||
@tab IRC link
|
||
@item @samp{info:org#External links}
|
||
@tab Info node link
|
||
@item @samp{shell:ls *.org}
|
||
@tab A shell command
|
||
@item @samp{elisp:org-agenda}
|
||
@tab Interactive Elisp command
|
||
@item @samp{elisp:(find-file-other-frame "Elisp.org")}
|
||
@tab Elisp form to evaluate
|
||
@end multitable
|
||
|
||
@cindex VM links
|
||
@cindex Wanderlust links
|
||
On top of these built-in link types, some are available through the
|
||
@samp{contrib/} directory (see @ref{Installation}). For example, these links to
|
||
VM or Wanderlust messages are available when you load the
|
||
corresponding libraries from the @samp{contrib/} directory:
|
||
|
||
@multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaa}
|
||
@item @samp{vm:folder}
|
||
@tab VM folder link
|
||
@item @samp{vm:folder#id}
|
||
@tab VM message link
|
||
@item @samp{vm://myself@@some.where.org/folder#id}
|
||
@tab VM on remote machine
|
||
@item @samp{vm-imap:account:folder}
|
||
@tab VM IMAP folder link
|
||
@item @samp{vm-imap:account:folder#id}
|
||
@tab VM IMAP message link
|
||
@item @samp{wl:folder}
|
||
@tab Wanderlust folder link
|
||
@item @samp{wl:folder#id}
|
||
@tab Wanderlust message link
|
||
@end multitable
|
||
|
||
For customizing Org to add new link types, see @ref{Adding Hyperlink Types}.
|
||
|
||
A link should be enclosed in double brackets and may contain
|
||
a descriptive text to be displayed instead of the URL (see @ref{Link Format}), for example:
|
||
|
||
@example
|
||
[[http://www.gnu.org/software/emacs/][GNU Emacs]]
|
||
@end example
|
||
|
||
@noindent
|
||
If the description is a file name or URL that points to an image, HTML
|
||
export (see @ref{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.
|
||
|
||
@cindex square brackets, around links
|
||
@cindex angular brackets, around links
|
||
@cindex plain text external links
|
||
Org also finds external links in the normal text and activates them as
|
||
links. If spaces must be part of the link (for example in
|
||
@samp{bbdb:Richard Stallman}), or if you need to remove ambiguities about
|
||
the end of the link, enclose them in square or angular brackets.
|
||
|
||
@node Handling Links
|
||
@section Handling Links
|
||
|
||
@cindex links, handling
|
||
|
||
Org provides methods to create a link in the correct syntax, to insert
|
||
it into an Org file, and to follow the link.
|
||
|
||
@findex org-store-link
|
||
@cindex storing links
|
||
The main function is @code{org-store-link}, called with @kbd{M-x org-store-link}. Because of its importance, we suggest to bind it
|
||
to a widely available key (see @ref{Activation}). It stores a link to the
|
||
current location. The link is stored for later insertion into an Org
|
||
buffer---see below. What kind of link is created depends on the
|
||
current buffer:
|
||
|
||
@table @asis
|
||
@item @emph{Org mode buffers}
|
||
For Org files, if there is a @samp{<<target>>} at the cursor, the link
|
||
points to the target. Otherwise it points to the current
|
||
headline, which is also the description@footnote{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.}.
|
||
|
||
@vindex org-link-to-org-use-id
|
||
@cindex @samp{CUSTOM_ID}, property
|
||
@cindex @samp{ID}, property
|
||
If the headline has a @samp{CUSTOM_ID} property, store a link to this
|
||
custom ID. In addition or alternatively, depending on the value
|
||
of @code{org-link-to-org-use-id}, create and/or use a globally unique
|
||
ID property for the link@footnote{The Org Id library must first be loaded, either through
|
||
@code{org-customize}, by enabling @code{id} in @code{org-modules}, or by adding
|
||
@code{(require 'org-id)} in your Emacs init file.}. 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. Later, when inserting the
|
||
link, you need to decide which one to use.
|
||
|
||
@item @emph{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 from the author and the
|
||
subject.
|
||
|
||
@item @emph{Web browsers: W3, W3M and EWW}
|
||
Here the link is the current URL, with the page title as
|
||
description.
|
||
|
||
@item @emph{Contacts: BBDB}
|
||
Links created in a BBDB buffer point to the current entry.
|
||
|
||
@item @emph{Chat: IRC}
|
||
@vindex org-irc-links-to-logs
|
||
For IRC links, if the variable @code{org-irc-link-to-logs} is
|
||
non-@code{nil}, create a @samp{file} style link to the relevant point in
|
||
the logs for the current conversation. Otherwise store an @samp{irc}
|
||
style link to the user/channel/server under the point.
|
||
|
||
@item @emph{Other files}
|
||
For any other file, the link points to the file, with a search
|
||
string (see @ref{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. If the
|
||
automatically created link is not working correctly or accurately
|
||
enough, you can write custom functions to select the search
|
||
string and to do the search for particular file types (see
|
||
@ref{Custom Searches}).
|
||
|
||
You can also define dedicated links to other files. See @ref{Adding Hyperlink Types}.
|
||
|
||
@item @emph{Agenda view}
|
||
When the cursor is in an agenda view, the created link points to
|
||
the entry referenced by the current line.
|
||
@end table
|
||
|
||
From an Org buffer, the following commands create, navigate or, more
|
||
generally, act on links.
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-l} (@code{org-insert-link})
|
||
@kindex C-c C-l
|
||
@findex org-insert-link
|
||
@cindex link completion
|
||
@cindex completion, of links
|
||
@cindex inserting links
|
||
@vindex org-keep-stored-link-after-insertion
|
||
Insert a link@footnote{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.}. 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@footnote{After insertion of a stored link, the link will be removed
|
||
from the list of stored links. To keep it in the list later use, use
|
||
a triple @kbd{C-u} prefix argument to @kbd{C-c C-l}, or
|
||
configure the option @code{org-keep-stored-link-after-insertion}.}. If some text was selected at this
|
||
time, it becomes the default description.
|
||
|
||
@table @asis
|
||
@item @emph{Inserting stored links}
|
||
All links stored during the current session are part of the
|
||
history for this prompt, so you can access them with
|
||
@kbd{@key{UP}} and @kbd{@key{DOWN}} (or @kbd{M-p},
|
||
@kbd{M-n}).
|
||
|
||
@item @emph{Completion support}
|
||
Completion with @kbd{@key{TAB}} helps you to insert valid link
|
||
prefixes like @samp{http} or @samp{ftp}, including the prefixes defined
|
||
through link abbreviations (see @ref{Link Abbreviations}). If you
|
||
press @kbd{@key{RET}} after inserting only the prefix, Org
|
||
offers specific completion support for some link types@footnote{This works if a function has been defined in the @code{:complete}
|
||
property of a link in @code{org-link-parameters}.}.
|
||
For example, if you type @kbd{f i l e @key{RET}}---alternative
|
||
access: @kbd{C-u C-c C-l}, see below---Org offers file
|
||
name completion, and after @kbd{b b d b @key{RET}} you can
|
||
complete contact names.
|
||
@end table
|
||
|
||
@item @kbd{C-u C-c C-l}
|
||
@cindex file name completion
|
||
@cindex completion, of file names
|
||
@kindex C-u C-c C-l
|
||
When @kbd{C-c C-l} is called with a @kbd{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 @samp{../}. Otherwise an absolute path is used, if
|
||
possible with @samp{~/} for your home directory. You can force an
|
||
absolute path with two @kbd{C-u} prefixes.
|
||
|
||
@item @kbd{C-c C-l} (with cursor on existing link)
|
||
@cindex following links
|
||
When the cursor is on an existing link, @kbd{C-c C-l} allows
|
||
you to edit the link and description parts of the link.
|
||
|
||
@item @kbd{C-c C-o} (@code{org-open-at-point})
|
||
@kindex C-c C-o
|
||
@findex org-open-at-point
|
||
@vindex org-file-apps
|
||
Open link at point. This launches a web browser for URL (using
|
||
@code{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 the cursor is on an internal link, this command runs
|
||
the corresponding search. When the cursor is on a TAG list in
|
||
a headline, it creates the corresponding TAGS view. If the
|
||
cursor is on a timestamp, it compiles the agenda for that date.
|
||
Furthermore, it visits text and remote files in @samp{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 @code{org-file-apps}. If you want to override the default
|
||
application and visit the file with Emacs, use a @kbd{C-u}
|
||
prefix. If you want to avoid opening in Emacs, use a @kbd{C-u C-u} prefix.
|
||
|
||
@vindex org-link-frame-setup
|
||
If the cursor 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
|
||
@code{org-link-frame-setup}.
|
||
|
||
@item @kbd{@key{RET}}
|
||
@vindex org-return-follows-link
|
||
@kindex RET
|
||
When @code{org-return-follows-link} is set, @kbd{@key{RET}} also
|
||
follows the link at point.
|
||
|
||
@item @kbd{mouse-2} or @kbd{mouse-1}
|
||
@kindex mouse-2
|
||
@kindex mouse-1
|
||
On links, @kbd{mouse-1} and @kbd{mouse-2} opens the
|
||
link just as @kbd{C-c C-o} does.
|
||
|
||
@item @kbd{mouse-3}
|
||
@vindex org-display-internal-link-with-indirect-buffer
|
||
@kindex mouse-3
|
||
Like @kbd{mouse-2}, but force file links to be opened with
|
||
Emacs, and internal links to be displayed in another
|
||
window@footnote{See the variable @code{org-display-internal-link-with-indirect-buffer}.}.
|
||
|
||
@item @kbd{C-c C-x C-v} (@code{org-toggle-inline-images})
|
||
@cindex inlining images
|
||
@cindex images, inlining
|
||
@vindex org-startup-with-inline-images
|
||
@kindex C-c C-x C-v
|
||
@findex org-toggle-inline-images
|
||
Toggle the inline display of linked images. Normally this only
|
||
inlines images that have no description part in the link, i.e.,
|
||
images that are inlined during export. 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 @code{org-startup-with-inline-images}@footnote{The variable @code{org-startup-with-inline-images} can be set
|
||
within a buffer with the @samp{STARTUP} options @samp{inlineimages} and
|
||
@samp{noinlineimages}.}.
|
||
|
||
@item @kbd{C-c %} (@code{org-mark-ring-push})
|
||
@kindex C-c %
|
||
@findex org-mark-ring-push
|
||
@cindex mark ring
|
||
Push the current position onto the mark ring, to be able to
|
||
return easily. Commands following an internal link do this
|
||
automatically.
|
||
|
||
@item @kbd{C-c &} (@code{org-mark-ring-goto})
|
||
@kindex C-c &
|
||
@findex org-mark-ring-goto
|
||
@cindex links, returning to
|
||
Jump back to a recorded position. A position is recorded by the
|
||
commands following internal links, and by @kbd{C-c %}.
|
||
Using this command several times in direct succession moves
|
||
through a ring of previously recorded positions.
|
||
|
||
@item @kbd{C-c C-x C-n} (@code{org-next-link})
|
||
@itemx @kbd{C-c C-x C-p} (@code{org-previous-link})
|
||
@kindex C-c C-x C-p
|
||
@findex org-previous-link
|
||
@kindex C-c C-x C-n
|
||
@findex org-next-link
|
||
@cindex links, finding next/previous
|
||
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 @kbd{M-n} and @kbd{M-p}.
|
||
|
||
@lisp
|
||
(add-hook 'org-load-hook
|
||
(lambda ()
|
||
(define-key org-mode-map "\M-n" 'org-next-link)
|
||
(define-key org-mode-map "\M-p" 'org-previous-link)))
|
||
@end lisp
|
||
@end table
|
||
|
||
@node Using Links Outside Org
|
||
@section Using Links Outside Org
|
||
|
||
@findex org-insert-link-global
|
||
@findex org-open-at-point-global
|
||
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:
|
||
@code{org-insert-link-global} and @code{org-open-at-point-global}.
|
||
|
||
You might want to bind them to globally available keys. See
|
||
@ref{Activation} for some advice.
|
||
|
||
@node Link Abbreviations
|
||
@section Link Abbreviations
|
||
|
||
@cindex link abbreviations
|
||
@cindex abbreviation, links
|
||
|
||
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
|
||
|
||
@example
|
||
[[linkword:tag][description]]
|
||
@end example
|
||
|
||
@noindent
|
||
@vindex org-link-abbrev-alist
|
||
where the tag is optional. The @emph{linkword} must be a word, starting
|
||
with a letter, followed by letters, numbers, @samp{-}, and @samp{_}.
|
||
Abbreviations are resolved according to the information in the
|
||
variable @code{org-link-abbrev-alist} that relates the linkwords to
|
||
replacement text. Here is an example:
|
||
|
||
@lisp
|
||
(setq org-link-abbrev-alist
|
||
'(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=")
|
||
("url-to-ja" . "http://translate.google.fr/translate?sl=en&tl=ja&u=%h")
|
||
("google" . "http://www.google.com/search?q=")
|
||
("gmap" . "http://maps.google.com/maps?q=%s")
|
||
("omap" . "http://nominatim.openstreetmap.org/search?q=%s&polygon=1")
|
||
("ads" . "http://adsabs.harvard.edu/cgi-bin/nph-abs_connect?author=%s&db_key=AST")))
|
||
@end lisp
|
||
|
||
If the replacement text contains the string @samp{%s}, it is replaced with
|
||
the tag. Using @samp{%h} instead of @samp{%s} percent-encodes the tag (see the
|
||
example above, where we need to encode the URL parameter). Using
|
||
@samp{%(my-function)} passes the tag to a custom 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 function that will be
|
||
called with the tag as the only argument to create the link.
|
||
|
||
With the above setting, you could link to a specific bug with
|
||
@samp{[[bugzilla:129]]}, search the web for @samp{OrgMode} with @samp{[[google:OrgMode]]},
|
||
show the map location of the Free Software Foundation @samp{[[gmap:51
|
||
Franklin Street, Boston]]} or of Carsten office @samp{[[omap:Science Park 904,
|
||
Amsterdam, The Netherlands]]} and find out what the Org author is doing
|
||
besides Emacs hacking with @samp{[[ads:Dominik,C]]}.
|
||
|
||
If you need special abbreviations just for a single Org buffer, you
|
||
can define them in the file with
|
||
|
||
@cindex @samp{LINK}, keyword
|
||
@example
|
||
#+LINK: bugzilla http://10.1.2.9/bugzilla/show_bug.cgi?id=
|
||
#+LINK: google http://www.google.com/search?q=%s
|
||
@end example
|
||
|
||
@noindent
|
||
In-buffer completion (see @ref{Completion}) can be used after @samp{[} to
|
||
complete link abbreviations. You may also define a function that
|
||
implements special (e.g., completion) support for inserting such
|
||
a link with @kbd{C-c C-l}. Such a function should not accept any
|
||
arguments, and return the full link with prefix. You can set the link
|
||
completion function like this:
|
||
|
||
@lisp
|
||
(org-link-set-parameter "type" :complete #'some-completion-function)
|
||
@end lisp
|
||
|
||
@node Search Options
|
||
@section Search Options in File Links
|
||
|
||
@cindex search option in file links
|
||
@cindex file links, searching
|
||
|
||
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@footnote{For backward compatibility, line numbers can also follow a
|
||
single colon.}. For
|
||
example, when the command @code{org-store-link} creates a link (see
|
||
@ref{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 @kbd{C-c C-o}.
|
||
|
||
Here is the syntax of the different ways to attach a search to a file
|
||
link, together with an explanation:
|
||
|
||
@example
|
||
[[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/]]
|
||
@end example
|
||
|
||
@table @asis
|
||
@item @samp{255}
|
||
Jump to line 255.
|
||
|
||
@item @samp{My Target}
|
||
Search for a link target @samp{<<My Target>>}, or do a text search for
|
||
@samp{my target}, similar to the search in internal links, see
|
||
@ref{Internal Links}. In HTML export (see @ref{HTML Export}), such a file
|
||
link becomes a HTML reference to the corresponding named anchor
|
||
in the linked file.
|
||
|
||
@item @samp{*My Target}
|
||
In an Org file, restrict search to headlines.
|
||
|
||
@item @samp{#my-custom-id}
|
||
Link to a heading with a @samp{CUSTOM_ID} property
|
||
|
||
@item @samp{/REGEXP/}
|
||
Do a regular expression search for @var{REGEXP}. This uses
|
||
the Emacs command @code{occur} to list all matches in a separate
|
||
window. If the target file is in Org mode, @code{org-occur} is used
|
||
to create a sparse tree with the matches.
|
||
@end table
|
||
|
||
As a degenerate case, a file link with an empty file name can be used
|
||
to search the current file. For example, @samp{[[file:::find me]]} does
|
||
a search for @samp{find me} in the current file, just as @samp{[[find me]]} would.
|
||
|
||
@node Custom Searches
|
||
@section Custom Searches
|
||
|
||
@cindex custom search strings
|
||
@cindex search strings, custom
|
||
|
||
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, Bib@TeX{} database files have many entries like
|
||
@code{year="1993"} which would not result in good search strings, because
|
||
the only unique identification for a Bib@TeX{} entry is the citation key.
|
||
|
||
@vindex org-create-file-search-functions
|
||
@vindex org-execute-file-search-functions
|
||
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 @code{add-hook}, these functions
|
||
need to be added to the hook variables
|
||
@code{org-create-file-search-functions} and
|
||
@code{org-execute-file-search-functions}. See the docstring for these
|
||
variables for more information. Org actually uses this mechanism for
|
||
Bib@TeX{} database files, and you can use the corresponding code as an
|
||
implementation example. See the file @samp{org-bibtex.el}.
|
||
|
||
@node TODO Items
|
||
@chapter TODO Items
|
||
|
||
@cindex TODO items
|
||
|
||
Org mode does not maintain TODO lists as separate documents@footnote{Of course, you can make a document that contains only long
|
||
lists of TODO items, but this is not required.}.
|
||
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.
|
||
@end menu
|
||
|
||
@node TODO Basics
|
||
@section Basic TODO Functionality
|
||
|
||
Any headline becomes a TODO item when it starts with the word @samp{TODO},
|
||
for example:
|
||
|
||
@example
|
||
*** TODO Write letter to Sam Fortune
|
||
@end example
|
||
|
||
@noindent
|
||
The most important commands to work with TODO entries are:
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-t} (@code{org-todo})
|
||
@kindex C-c C-t
|
||
@cindex cycling, of TODO states
|
||
Rotate the TODO state of the current item among
|
||
|
||
@example
|
||
,-> (unmarked) -> TODO -> DONE --.
|
||
'--------------------------------'
|
||
@end example
|
||
|
||
If TODO keywords have fast access keys (see @ref{Fast access to TODO states}), prompt for a TODO keyword through the fast
|
||
selection interface; this is the default behavior when
|
||
@code{org-use-fast-todo-selection} is non-@code{nil}.
|
||
|
||
The same rotation can also be done ``remotely'' from the timeline
|
||
and agenda buffers with the @kbd{t} command key (see
|
||
@ref{Agenda Commands}).
|
||
|
||
@item @kbd{C-u C-c C-t}
|
||
@kindex C-u C-c C-t
|
||
When TODO keywords have no selection keys, select a specific
|
||
keyword using completion; otherwise force cycling through TODO
|
||
states with no prompt. When @code{org-use-fast-todo-selection} is set
|
||
to @code{prefix}, use the fast selection interface.
|
||
|
||
@item @kbd{S-@key{RIGHT}} @kbd{S-@key{LEFT}}
|
||
@kindex S-RIGHT
|
||
@kindex S-LEFT
|
||
@vindex org-treat-S-cursor-todo-selection-as-state-change
|
||
Select the following/preceding TODO state, similar to cycling.
|
||
Useful mostly if more than two TODO states are possible (see
|
||
@ref{TODO Extensions}). See also @ref{Conflicts}, for a discussion of the interaction with
|
||
@code{shift-selection-mode}. See also the variable
|
||
@code{org-treat-S-cursor-todo-selection-as-state-change}.
|
||
|
||
@item @kbd{C-c / t} (@code{org-show-todo-tree})
|
||
@kindex C-c / t
|
||
@cindex sparse tree, for TODO
|
||
@vindex org-todo-keywords
|
||
@findex org-show-todo-tree
|
||
View TODO items in a @emph{sparse tree} (see @ref{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 @kbd{C-c / T}, search for a specific
|
||
TODO. You are prompted for the keyword, and you can also give
|
||
a list of keywords like @samp{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
|
||
@code{org-todo-keywords}. With two prefix arguments, find all TODO
|
||
states, both un-done and done.
|
||
|
||
@item @kbd{C-c a t} (@code{org-todo-list})
|
||
@kindex C-c a t
|
||
Show the global TODO list. Collects the TODO items (with
|
||
not-DONE states) from all agenda files (see @ref{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 @ref{Agenda Commands}). See @ref{Global TODO list}, for more information.
|
||
|
||
@item @kbd{S-M-@key{RET}} (@code{org-insert-todo-heading})
|
||
@kindex S-M-RET
|
||
@findex org-insert-todo-heading
|
||
Insert a new TODO entry below the current one.
|
||
@end table
|
||
|
||
@vindex org-todo-state-tags-triggers
|
||
@noindent
|
||
Changing a TODO state can also trigger tag changes. See the docstring
|
||
of the option @code{org-todo-state-tags-triggers} for details.
|
||
|
||
@node TODO Extensions
|
||
@section Extended Use of TODO Keywords
|
||
|
||
@cindex extended TODO keywords
|
||
|
||
@vindex org-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 @emph{TODO keywords} (stored in @code{org-todo-keywords}). With special
|
||
setup, the TODO keyword system can work differently in different
|
||
files.
|
||
|
||
Note that @emph{tags} are another way to classify headlines in general and
|
||
TODO items in particular (see @ref{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.
|
||
@end menu
|
||
|
||
@node Workflow states
|
||
@subsection TODO keywords as workflow states
|
||
|
||
@cindex TODO workflow
|
||
@cindex workflow states as TODO keywords
|
||
|
||
You can use TODO keywords to indicate different @emph{sequential} states in
|
||
the process of working on an item, for example@footnote{Changing the variable @code{org-todo-keywords} only becomes
|
||
effective after restarting Org mode in a buffer.}:
|
||
|
||
@lisp
|
||
(setq org-todo-keywords
|
||
'((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED")))
|
||
@end lisp
|
||
|
||
The vertical bar separates the TODO keywords (states that @emph{need
|
||
action}) from the DONE states (which need @emph{no further action}). If
|
||
you do not provide the separator bar, the last state is used as the
|
||
DONE state.
|
||
|
||
@cindex completion, of TODO keywords
|
||
With this setup, the command @kbd{C-c C-t} cycles an entry from
|
||
@samp{TODO} to @samp{FEEDBACK}, then to @samp{VERIFY}, and finally to @samp{DONE} and
|
||
@samp{DELEGATED}. You may also use a numeric prefix argument to quickly
|
||
select a specific state. For example @kbd{C-3 C-c C-t} changes
|
||
the state immediately to @samp{VERIFY}. Or you can use @kbd{S-@key{LEFT}}
|
||
to go backward through the sequence. If you define many keywords, you
|
||
can use in-buffer completion (see @ref{Completion}) or even a special
|
||
one-key selection scheme (see @ref{Fast access to TODO states}) to insert
|
||
these words into the buffer. Changing a TODO state can be logged with
|
||
a timestamp, see @ref{Tracking TODO state changes}, for more information.
|
||
|
||
@node TODO types
|
||
@subsection TODO keywords as types
|
||
|
||
@cindex TODO types
|
||
@cindex names as TODO keywords
|
||
@cindex types as TODO keywords
|
||
|
||
The second possibility is to use TODO keywords to indicate different
|
||
@emph{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 would be set up
|
||
like this:
|
||
|
||
@lisp
|
||
(setq org-todo-keywords '((type "Fred" "Sara" "Lucy" "|" "DONE")))
|
||
@end lisp
|
||
|
||
In this case, different keywords do not indicate a sequence, 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 @kbd{C-c C-t}@footnote{This is also true for the @kbd{t} command in the timeline
|
||
and agenda buffers.}. 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
|
||
@kbd{C-c C-t} again, it will switch from any name directly to
|
||
@samp{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 @kbd{C-c / t}.
|
||
For example, to see all things Lucy has to do, you would use
|
||
@kbd{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: @kbd{C-3 C-c a t}.
|
||
|
||
@node Multiple sets in one file
|
||
@subsection Multiple keyword sets in one file
|
||
|
||
@cindex TODO keyword sets
|
||
|
||
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:
|
||
|
||
@lisp
|
||
(setq org-todo-keywords
|
||
'((sequence "TODO" "|" "DONE")
|
||
(sequence "REPORT" "BUG" "KNOWNCAUSE" "|" "FIXED")
|
||
(sequence "|" "CANCELED")))
|
||
@end lisp
|
||
|
||
The keywords should all be different, this helps Org mode to keep
|
||
track of which subsequence should be used for a given entry. In this
|
||
setup, @kbd{C-c C-t} only operates within a subsequence, so it
|
||
switches from @samp{DONE} to (nothing) to @samp{TODO}, and from @samp{FIXED} to
|
||
(nothing) to @samp{REPORT}. Therefore you need a mechanism to initially
|
||
select the correct sequence. Besides the obvious ways like typing
|
||
a keyword or using completion, you may also apply the following
|
||
commands:
|
||
|
||
@table @asis
|
||
@item @kbd{C-u C-u C-c C-t}
|
||
@itemx @kbd{C-S-@key{RIGHT}}
|
||
@itemx @kbd{C-S-@key{LEFT}}
|
||
@kindex C-S-RIGHT
|
||
@kindex C-S-LEFT
|
||
@kindex C-u C-u C-c C-t
|
||
These keys jump from one TODO subset to the next. In the above
|
||
example, @kbd{C-u C-u C-c C-t} or @kbd{C-S-@key{RIGHT}} would
|
||
jump from @samp{TODO} or @samp{DONE} to @samp{REPORT}, and any of the words in
|
||
the second row to @samp{CANCELED}. Note that the @kbd{C-S-} key
|
||
binding conflict with @code{shift-selection-mode} (see @ref{Conflicts}).
|
||
|
||
@item @kbd{S-@key{RIGHT}}
|
||
@itemx @kbd{S-@key{LEFT}}
|
||
@kindex S-RIGHT
|
||
@kindex S-LEFT
|
||
@kbd{S-@key{LEFT}} and @kbd{S-@key{RIGHT}} walk through @emph{all}
|
||
keywords from all sets, so for example @kbd{S-@key{RIGHT}} would
|
||
switch from @samp{DONE} to @samp{REPORT} in the example above. For
|
||
a discussion of the interaction with @code{shift-selection-mode}, see
|
||
@ref{Conflicts}.
|
||
@end table
|
||
|
||
@node Fast access to TODO states
|
||
@subsection 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@footnote{All characters are allowed except @samp{@@}, @samp{^} and @samp{!}, which have
|
||
a special meaning here.}. For
|
||
example:
|
||
|
||
@lisp
|
||
(setq org-todo-keywords
|
||
'((sequence "TODO(t)" "|" "DONE(d)")
|
||
(sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)")
|
||
(sequence "|" "CANCELED(c)")))
|
||
@end lisp
|
||
|
||
@vindex org-fast-tag-selection-include-todo
|
||
If you then press @kbd{C-c C-t} followed by the selection key,
|
||
the entry is switched to this state. @kbd{@key{SPC}} can be used to
|
||
remove any TODO keyword from an entry@footnote{Check also the variable @code{org-fast-tag-selection-include-todo},
|
||
it allows you to change the TODO state through the tags interface
|
||
(@ref{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.}.
|
||
|
||
@node Per-file keywords
|
||
@subsection Setting up keywords for individual files
|
||
|
||
@cindex keyword options
|
||
@cindex per-file keywords
|
||
@cindex @samp{TODO}, keyword
|
||
@cindex @samp{TYP_TODO}, keyword
|
||
@cindex @samp{SEQ_TODO}, keyword
|
||
|
||
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:
|
||
|
||
@example
|
||
#+TODO: TODO FEEDBACK VERIFY | DONE CANCELED
|
||
@end example
|
||
|
||
@noindent
|
||
you may also write @samp{#+SEQ_TODO} to be explicit about the
|
||
interpretation, but it means the same as @samp{#+TODO}, or
|
||
|
||
@example
|
||
#+TYP_TODO: Fred Sara Lucy Mike | DONE
|
||
@end example
|
||
|
||
A setup for using several sets in parallel would be:
|
||
|
||
@example
|
||
#+TODO: TODO | DONE
|
||
#+TODO: REPORT BUG KNOWNCAUSE | FIXED
|
||
#+TODO: | CANCELED
|
||
@end example
|
||
|
||
@cindex completion, of option keywords
|
||
@kindex M-TAB
|
||
@noindent
|
||
To make sure you are using the correct keyword, type @samp{#+} into the
|
||
buffer and then use @kbd{M-@key{TAB}} completion.
|
||
|
||
@cindex DONE, final TODO keyword
|
||
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 @kbd{C-c C-c} with the cursor still in the line to
|
||
make the changes known to Org mode@footnote{Org mode parses these lines only when Org mode is activated
|
||
after visiting a file. @kbd{C-c C-c} with the cursor in a line
|
||
starting with @samp{#+} is simply restarting Org mode for the current
|
||
buffer.}.
|
||
|
||
@node Faces for TODO keywords
|
||
@subsection Faces for TODO keywords
|
||
|
||
@cindex faces, for TODO keywords
|
||
|
||
@vindex org-todo, face
|
||
@vindex org-done, face
|
||
@vindex org-todo-keyword-faces
|
||
Org mode highlights TODO keywords with special faces: @code{org-todo} for
|
||
keywords indicating that an item still has to be acted upon, and
|
||
@code{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
|
||
@code{org-todo-keyword-faces}. For example:
|
||
|
||
@lisp
|
||
(setq org-todo-keyword-faces
|
||
'(("TODO" . org-warning) ("STARTED" . "yellow")
|
||
("CANCELED" . (:foreground "blue" :weight bold))))
|
||
@end lisp
|
||
|
||
@vindex org-faces-easy-properties
|
||
While using a list with face properties as shown for @samp{CANCELED}
|
||
@emph{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 @code{org-faces-easy-properties}
|
||
determines if that color is interpreted as a foreground or
|
||
a background color.
|
||
|
||
@node TODO dependencies
|
||
@subsection TODO dependencies
|
||
|
||
@cindex TODO dependencies
|
||
@cindex dependencies, of TODO states
|
||
|
||
@vindex org-enforce-todo-dependencies
|
||
@cindex @samp{ORDERED}, property
|
||
The structure of Org files---hierarchy and lists---makes it easy to
|
||
define TODO dependencies. Usually, a parent TODO task should not be
|
||
marked DONE until all subtasks, defined as children tasks, are marked
|
||
as DONE. And sometimes there is a logical sequence to a number of
|
||
(sub)tasks, so that one task cannot be acted upon before all siblings
|
||
above it are done. If you customize the variable
|
||
@code{org-enforce-todo-dependencies}, Org blocks entries from changing
|
||
state to DONE while they have children that are not DONE.
|
||
Furthermore, if an entry has a property @samp{ORDERED}, each of its
|
||
children is blocked until all earlier siblings are marked DONE. Here
|
||
is an example:
|
||
|
||
@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)
|
||
@end example
|
||
|
||
@cindex TODO dependencies, NOBLOCKING
|
||
@cindex NOBLOCKING, property
|
||
You can ensure an entry is never blocked by using the @samp{NOBLOCKING}
|
||
property:
|
||
|
||
@example
|
||
* This entry is never blocked
|
||
:PROPERTIES:
|
||
:NOBLOCKING: t
|
||
:END:
|
||
@end example
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-x o} (@code{org-toggle-ordered-property})
|
||
@kindex C-c C-x o
|
||
@findex org-toggle-ordered-property
|
||
@vindex org-track-ordered-property-with-tag
|
||
Toggle the @samp{ORDERED} property of the current entry. 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 @emph{track} the value of this property with a tag for better
|
||
visibility, customize the variable
|
||
@code{org-track-ordered-property-with-tag}.
|
||
|
||
@item @kbd{C-u C-u C-u C-c C-t}
|
||
@kindex C-u C-u C-u C-c C-t
|
||
Change TODO state, circumventing any state blocking.
|
||
@end table
|
||
|
||
@vindex org-agenda-dim-blocked-tasks
|
||
If you set the variable @code{org-agenda-dim-blocked-tasks}, TODO entries
|
||
that cannot be closed because of such dependencies are shown in
|
||
a dimmed font or even made invisible in agenda views (see @ref{Agenda Views}).
|
||
|
||
@cindex checkboxes and TODO dependencies
|
||
@vindex org-enforce-todo-dependencies
|
||
You can also block changes of TODO states by looking at checkboxes
|
||
(see @ref{Checkboxes}). If you set the variable
|
||
@code{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 contributed module @samp{org-depend.el}.
|
||
|
||
@node Progress Logging
|
||
@section Progress Logging
|
||
|
||
@cindex progress logging
|
||
@cindex logging, of progress
|
||
|
||
Org mode can automatically record a timestamp and possibly 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 @ref{Clocking Work Time}.
|
||
|
||
@menu
|
||
* Closing items:: When was this entry marked DONE?
|
||
* Tracking TODO state changes:: When did the status change?
|
||
* Tracking your habits:: How consistent have you been?
|
||
@end menu
|
||
|
||
@node Closing items
|
||
@subsection Closing items
|
||
|
||
The most basic logging is to keep track of @emph{when} a certain TODO item
|
||
was finished. This is achieved with@footnote{The corresponding in-buffer setting is: @samp{#+STARTUP: logdone}.}
|
||
|
||
@lisp
|
||
(setq org-log-done 'time)
|
||
@end lisp
|
||
|
||
@vindex org-closed-keep-when-no-todo
|
||
@noindent
|
||
Then each time you turn an entry from a TODO (not-done) state into any
|
||
of the DONE states, a line @samp{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 @kbd{C-c C-t @key{SPC}} for example), that line is also removed, unless you set
|
||
@code{org-closed-keep-when-no-todo} to non-@code{nil}. If you want to record
|
||
a note along with the timestamp, use@footnote{The corresponding in-buffer setting is: @samp{#+STARTUP:
|
||
lognotedone}.}
|
||
|
||
@lisp
|
||
(setq org-log-done 'note)
|
||
@end lisp
|
||
|
||
@noindent
|
||
You are then be prompted for a note, and that note is stored below the
|
||
entry with a @samp{Closing Note} heading.
|
||
|
||
@node Tracking TODO state changes
|
||
@subsection Tracking TODO state changes
|
||
|
||
@cindex drawer, for state change recording
|
||
|
||
@vindex org-log-states-order-reversed
|
||
@vindex org-log-into-drawer
|
||
@cindex @samp{LOG_INTO_DRAWER}, property
|
||
When TODO keywords are used as workflow states (see @ref{Workflow states, , *Workflow states}),
|
||
you might want to 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 for a change. These records are
|
||
inserted after the headline as an itemized list, newest first@footnote{See the variable @code{org-log-states-order-reversed}.}.
|
||
When taking a lot of notes, you might want to get the notes out of the
|
||
way into a drawer (see @ref{Drawers}). Customize the variable
|
||
@code{org-log-into-drawer} to get this behavior---the recommended drawer
|
||
for this is called @samp{LOGBOOK}@footnote{Note that the @samp{LOGBOOK} drawer is unfolded when pressing
|
||
@kbd{@key{SPC}} in the agenda to show an entry---use @kbd{C-u @key{SPC}} to keep it folded here.}. You can also overrule the
|
||
setting of this variable for a subtree by setting a @samp{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 @samp{!} (for a timestamp) or @samp{@@} (for
|
||
a note with timestamp) in parentheses after each keyword. For
|
||
example, with the setting
|
||
|
||
@lisp
|
||
(setq org-todo-keywords
|
||
'((sequence "TODO(t)" "WAIT(w@@/!)" "|" "DONE(d!)" "CANCELED(c@@)")))
|
||
@end lisp
|
||
|
||
@noindent
|
||
to record a timestamp without a note for TODO keywords configured with
|
||
@samp{@@}, just type @kbd{C-c C-c} to enter a blank note when prompted.
|
||
|
||
@vindex org-log-done
|
||
@noindent
|
||
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 @samp{DONE},
|
||
and that a note is recorded when switching to @samp{WAIT} or
|
||
@samp{CANCELED}@footnote{It is possible that Org mode records two timestamps when you
|
||
are using both @code{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.}. The setting for @samp{WAIT} is even more special: the
|
||
@samp{!} after the slash means that in addition to the note taken when
|
||
entering the state, a timestamp should be recorded when @emph{leaving} the
|
||
@samp{WAIT} state, if and only if the @emph{target} state does not configure
|
||
logging for entering it. So it has no effect when switching from
|
||
@samp{WAIT} to @samp{DONE}, because @samp{DONE} is configured to record a timestamp
|
||
only. But when switching from @samp{WAIT} back to @samp{TODO}, the @samp{/!} in the
|
||
@samp{WAIT} setting now triggers a timestamp even though @samp{TODO} has no
|
||
logging configured.
|
||
|
||
You can use the exact same syntax for setting logging preferences local
|
||
to a buffer:
|
||
|
||
@example
|
||
#+TODO: TODO(t) WAIT(w@@/!) | DONE(d!) CANCELED(c@@)
|
||
@end example
|
||
|
||
@cindex @samp{LOGGING}, property
|
||
In order to define logging settings that are local to a subtree or
|
||
a single item, define a @samp{LOGGING} property in this entry. Any
|
||
non-empty @samp{LOGGING} property resets all logging settings to @code{nil}.
|
||
You may then turn on logging for this specific tree using @samp{STARTUP}
|
||
keywords like @samp{lognotedone} or @samp{logrepeat}, as well as adding state
|
||
specific settings like @samp{TODO(!)}. For example:
|
||
|
||
@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:
|
||
@end example
|
||
|
||
@node Tracking your habits
|
||
@subsection Tracking your habits
|
||
|
||
@cindex habits
|
||
@cindex STYLE, property
|
||
|
||
Org has the ability to track the consistency of a special category of
|
||
TODO, called ``habits.'' A habit has the following properties:
|
||
|
||
@enumerate
|
||
@item
|
||
You have enabled the @code{habits} module by customizing the variable
|
||
@code{org-modules}.
|
||
|
||
@item
|
||
The habit is a TODO item, with a TODO keyword representing an open
|
||
state.
|
||
|
||
@item
|
||
The property @samp{STYLE} is set to the value @samp{habit}.
|
||
|
||
@item
|
||
The TODO has a scheduled date, usually with a @samp{.+} style repeat
|
||
interval. A @samp{++} style may be appropriate for habits with time
|
||
constraints, e.g., must be done on weekends, or a @samp{+} style for an
|
||
unusual habit that can have a backlog, e.g., weekly reports.
|
||
|
||
@item
|
||
The TODO may also have minimum and maximum ranges specified by
|
||
using the syntax @samp{.+2d/3d}, which says that you want to do the task
|
||
at least every three days, but at most every two days.
|
||
|
||
@item
|
||
You must also have state logging for the DONE state enabled (see
|
||
@ref{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.
|
||
@end enumerate
|
||
|
||
To give you an idea of what the above rules look like in action, here's an
|
||
actual habit with some history:
|
||
|
||
@example
|
||
** 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]
|
||
@end example
|
||
|
||
What this habit says is: I want to shave at most every 2 days---given
|
||
by the @samp{SCHEDULED} date and repeat interval---and at least every
|
||
4 days. If today is the 15th, then the habit first appears in the
|
||
agenda 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:
|
||
|
||
@table @asis
|
||
@item Blue
|
||
If the task was not to be done yet on that day.
|
||
@item Green
|
||
If the task could have been done on that day.
|
||
@item Yellow
|
||
If the task was going to be overdue the next day.
|
||
@item Red
|
||
If the task was overdue on that day.
|
||
@end table
|
||
|
||
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.
|
||
|
||
@table @asis
|
||
@item @code{org-habit-graph-column}
|
||
@vindex 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.
|
||
|
||
@item @code{org-habit-preceding-days}
|
||
@vindex org-habit-preceding-days
|
||
The amount of history, in days before today, to appear in
|
||
consistency graphs.
|
||
|
||
@item @code{org-habit-following-days}
|
||
@vindex org-habit-following-days
|
||
The number of days after today that appear in consistency graphs.
|
||
|
||
@item @code{org-habit-show-habits-only-for-today}
|
||
@vindex org-habit-show-habits-only-for-today
|
||
If non-@code{nil}, only show habits in today's agenda view. This is
|
||
set to true by default.
|
||
@end table
|
||
|
||
Lastly, pressing @kbd{K} in the agenda buffer causes habits to
|
||
temporarily be disabled and do not appear at all. Press @kbd{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.
|
||
|
||
@node Priorities
|
||
@section Priorities
|
||
|
||
@cindex priorities
|
||
@cindex priority cookie
|
||
|
||
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 @emph{priority cookie} into the headline of a TODO item,
|
||
like this
|
||
|
||
@example
|
||
*** TODO [#A] Write letter to Sam Fortune
|
||
@end example
|
||
|
||
@vindex org-priority-faces
|
||
@noindent
|
||
By default, Org mode supports three priorities: @samp{A}, @samp{B}, and @samp{C}.
|
||
@samp{A} is the highest priority. An entry without a cookie is treated
|
||
just like priority @samp{B}. Priorities make a difference only for sorting
|
||
in the agenda (see @ref{Weekly/daily agenda}); outside the agenda, they
|
||
have no inherent meaning to Org mode. The cookies can be highlighted
|
||
with special faces by customizing the variable @code{org-priority-faces}.
|
||
|
||
Priorities can be attached to any outline node; they do not need to be
|
||
TODO items.
|
||
|
||
@table @asis
|
||
@item @kbd{C-c ,} (@code{org-priority})
|
||
@kindex C-c ,
|
||
@findex org-priority
|
||
Set the priority of the current headline. The command prompts
|
||
for a priority character @samp{A}, @samp{B} or @samp{C}. When you press
|
||
@kbd{@key{SPC}} instead, the priority cookie is removed from the
|
||
headline. The priorities can also be changed ``remotely'' from the
|
||
timeline and agenda buffer with the @kbd{,} command (see
|
||
@ref{Agenda Commands}).
|
||
|
||
@item @kbd{S-@key{UP}} (@code{org-priority-up})
|
||
@itemx @kbd{S-@key{DOWN}} (@code{org-priority-down})
|
||
@kindex S-UP
|
||
@kindex S-DOWN
|
||
@findex org-priority-up
|
||
@findex org-priority-down
|
||
@vindex org-priority-start-cycle-with-default
|
||
Increase/decrease priority of current headline@footnote{See also the option @code{org-priority-start-cycle-with-default}.}. Note that
|
||
these keys are also used to modify timestamps (see @ref{Creating Timestamps}). See also @ref{Conflicts}, for
|
||
a discussion of the interaction with @code{shift-selection-mode}.
|
||
@end table
|
||
|
||
@vindex org-highest-priority
|
||
@vindex org-lowest-priority
|
||
@vindex org-default-priority
|
||
You can change the range of allowed priorities by setting the
|
||
variables @code{org-highest-priority}, @code{org-lowest-priority}, and
|
||
@code{org-default-priority}. 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):
|
||
|
||
@cindex @samp{PRIORITIES}, keyword
|
||
@example
|
||
#+PRIORITIES: A C B
|
||
@end example
|
||
|
||
@node Breaking Down Tasks
|
||
@section Breaking Down Tasks into Subtasks
|
||
|
||
@cindex tasks, breaking down
|
||
@cindex statistics, for TODO items
|
||
|
||
@vindex org-agenda-todo-list-sublevels
|
||
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@footnote{To keep subtasks out of the global TODO list, see the
|
||
@code{org-agenda-todo-list-sublevels}.}. To keep
|
||
the overview over the fraction of subtasks that are already completed,
|
||
insert either @samp{[/]} or @samp{[%]} anywhere in the headline. These cookies
|
||
are updated each time the TODO status of a child changes, or when
|
||
pressing @kbd{C-c C-c} on the cookie. For example:
|
||
|
||
@example
|
||
* Organize Party [33%]
|
||
** TODO Call people [1/2]
|
||
*** TODO Peter
|
||
*** DONE Sarah
|
||
** TODO Buy food
|
||
** DONE Talk to neighbor
|
||
@end example
|
||
|
||
@cindex @samp{COOKIE_DATA}, property
|
||
If a heading has both checkboxes and TODO children below it, the
|
||
meaning of the statistics cookie become ambiguous. Set the property
|
||
@samp{COOKIE_DATA} to either @samp{checkbox} or @samp{todo} to resolve this issue.
|
||
|
||
@vindex org-hierarchical-todo-statistics
|
||
If you would like to have the statistics cookie count any TODO entries
|
||
in the subtree (not just direct children), configure the variable
|
||
@code{org-hierarchical-todo-statistics}. To do this for a single subtree,
|
||
include the word @samp{recursive} into the value of the @samp{COOKIE_DATA}
|
||
property.
|
||
|
||
@example
|
||
* Parent capturing statistics [2/20]
|
||
:PROPERTIES:
|
||
:COOKIE_DATA: todo recursive
|
||
:END:
|
||
@end example
|
||
|
||
If you would like a TODO entry to automatically change to DONE when
|
||
all children are done, you can use the following setup:
|
||
|
||
@lisp
|
||
(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)
|
||
@end lisp
|
||
|
||
Another possibility is the use of checkboxes to identify (a hierarchy
|
||
of) a large number of subtasks (see @ref{Checkboxes}).
|
||
|
||
@node Checkboxes
|
||
@section Checkboxes
|
||
|
||
@cindex checkboxes
|
||
|
||
@vindex org-list-automatic-rules
|
||
Every item in a plain list@footnote{With the exception of description lists. But you can allow it
|
||
by modifying @code{org-list-automatic-rules} accordingly.} (see @ref{Plain Lists}) can be made into
|
||
a checkbox by starting it with the string @samp{[ ]}. This feature is
|
||
similar to TODO items (see @ref{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. To toggle a checkbox, use @kbd{C-c C-c}, or use the mouse (thanks to Piotr Zielinski's
|
||
@samp{org-mouse.el}).
|
||
|
||
Here is an example of a checkbox list.
|
||
|
||
@example
|
||
* 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
|
||
@end example
|
||
|
||
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.
|
||
|
||
@cindex statistics, for checkboxes
|
||
@cindex checkbox statistics
|
||
@cindex @samp{COOKIE_DATA}, property
|
||
@vindex org-hierarchical-checkbox-statistics
|
||
The @samp{[2/4]} and @samp{[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@footnote{Set the variable @code{org-hierarchical-checkbox-statistics} if you
|
||
want such cookies to count all checkboxes below the cookie, not just
|
||
those belonging to direct children.}. You have to insert the cookie yourself by typing
|
||
either @samp{[/]} or @samp{[%]}. With @samp{[/]} you get an @samp{n out of m} result, as
|
||
in the examples above. With @samp{[%]} you get information about the
|
||
percentage of checkboxes checked (in the above example, this would be
|
||
@samp{[50%]} and @samp{[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 @samp{COOKIE_DATA} to
|
||
either @samp{checkbox} or @samp{todo} to resolve this issue.
|
||
|
||
@cindex blocking, of checkboxes
|
||
@cindex checkbox blocking
|
||
@cindex @samp{ORDERED}, property
|
||
If the current outline node has an @samp{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.
|
||
|
||
@noindent
|
||
The following commands work with checkboxes:
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-c} (@code{org-toggle-checkbox})
|
||
@kindex C-c C-c
|
||
@findex 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@footnote{@kbd{C-u C-c C-c} on the @emph{first} item of a list with no
|
||
checkbox adds checkboxes to the rest of the list.}. With a double prefix
|
||
argument, set it to @samp{[-]}, which is considered to be an
|
||
intermediate state.
|
||
|
||
@item @kbd{C-c C-x C-b} (@code{org-toggle-checkbox})
|
||
@kindex C-c C-x C-b
|
||
Toggle checkbox status or---with prefix argument---checkbox
|
||
presence at point. With double prefix argument, set it to @samp{[-]},
|
||
which is considered to be an intermediate state.
|
||
|
||
@itemize
|
||
@item
|
||
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.
|
||
|
||
@item
|
||
If the cursor is in a headline, toggle checkboxes in the region
|
||
between this headline and the next---so @emph{not} the entire
|
||
subtree.
|
||
|
||
@item
|
||
If there is no active region, just toggle the checkbox at
|
||
point.
|
||
@end itemize
|
||
|
||
@item @kbd{M-S-@key{RET}} (@code{org-insert-todo-heading})
|
||
@kindex M-S-RET
|
||
@findex org-insert-todo-heading
|
||
Insert a new item with a checkbox. This works only if the cursor
|
||
is already in a plain list item (see @ref{Plain Lists}).
|
||
|
||
@item @kbd{C-c C-x o} (@code{org-toggle-ordered-property})
|
||
@kindex C-c C-x o
|
||
@findex org-toggle-ordered-property
|
||
@vindex org-track-ordered-property-with-tag
|
||
Toggle the @samp{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
|
||
@emph{track} the value of this property with a tag for better
|
||
visibility, customize @code{org-track-ordered-property-with-tag}.
|
||
|
||
@item @kbd{C-c #} (@code{org-update-statistics-cookies})
|
||
@kindex C-c #
|
||
@findex org-update-statistics-cookies
|
||
Update the statistics cookie in the current outline entry. When
|
||
called with a @kbd{C-u} prefix, update the entire file.
|
||
Checkbox statistic cookies are updated automatically if you
|
||
toggle checkboxes with @kbd{C-c C-c} and make new ones with
|
||
@kbd{M-S-@key{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.
|
||
@end table
|
||
|
||
@node Tags
|
||
@chapter Tags
|
||
|
||
@cindex tags
|
||
@cindex headline tagging
|
||
@cindex matching, tags
|
||
@cindex sparse tree, tag based
|
||
|
||
An excellent way to implement labels and contexts for
|
||
cross-correlating information is to assign @emph{tags} to headlines. Org
|
||
mode has extensive support for tags.
|
||
|
||
@vindex org-tag-faces
|
||
Every headline can contain a list of tags; they occur at the end of
|
||
the headline. Tags are normal words containing letters, numbers, @samp{_},
|
||
and @samp{@@}. Tags must be preceded and followed by a single colon, e.g.,
|
||
@samp{:work:}. Several tags can be specified, as in @samp{: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
|
||
@code{org-tag-faces}, in much the same way as you can for TODO keywords
|
||
(see @ref{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.
|
||
@end menu
|
||
|
||
@node Tag Inheritance
|
||
@section Tag Inheritance
|
||
|
||
@cindex tag inheritance
|
||
@cindex inheritance, of tags
|
||
@cindex sublevels, inclusion into tags match
|
||
|
||
@emph{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
|
||
|
||
@example
|
||
* Meeting with the French group :work:
|
||
** Summary by Frank :boss:notes:
|
||
*** TODO Prepare slides for him :action:
|
||
@end example
|
||
|
||
@noindent
|
||
the final heading has the tags @samp{work}, @samp{boss}, @samp{notes}, and @samp{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@footnote{As with all these in-buffer settings, pressing @kbd{C-c C-c} activates any changes in the line.}
|
||
|
||
@cindex @samp{FILETAGS}, keyword
|
||
@example
|
||
#+FILETAGS: :Peter:Boss:Secret:
|
||
@end example
|
||
|
||
@vindex org-use-tag-inheritance
|
||
@vindex org-tags-exclude-from-inheritance
|
||
@noindent
|
||
To limit tag inheritance to specific tags, or to turn it off entirely,
|
||
use the variables @code{org-use-tag-inheritance} and
|
||
@code{org-tags-exclude-from-inheritance}.
|
||
|
||
@vindex org-tags-match-list-sublevels
|
||
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@footnote{This is only true if the search does not involve more complex
|
||
tests including properties (see @ref{Property Searches}).}. 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 @code{org-tags-match-list-sublevels} (not
|
||
recommended).
|
||
|
||
@vindex org-agenda-use-tag-inheritance
|
||
Tag inheritance is relevant when the agenda search tries to match
|
||
a tag, either in the @code{tags} or @code{tags-todo} agenda types. In other
|
||
agenda types, @code{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
|
||
@code{org-agenda-use-tag-inheritance} to control this: the default value
|
||
includes all agenda types, but setting this to @code{nil} can really speed
|
||
up agenda generation.
|
||
|
||
@node Setting Tags
|
||
@section Setting Tags
|
||
|
||
@cindex setting tags
|
||
@cindex tags, setting
|
||
|
||
@kindex M-TAB
|
||
Tags can simply be typed into the buffer at the end of a headline.
|
||
After a colon, @kbd{M-@key{TAB}} offers completion on tags. There is
|
||
also a special command for inserting tags:
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-q} (@code{org-set-tags-command})
|
||
@kindex C-c C-q
|
||
@findex org-set-tags-command
|
||
@cindex completion, of tags
|
||
@vindex org-tags-column
|
||
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 @kbd{@key{RET}}, the tags are inserted
|
||
and aligned to @code{org-tags-column}. When called with
|
||
a @kbd{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 @ref{TODO Basics}).
|
||
|
||
@item @kbd{C-c C-c} (@code{org-set-tags-command})
|
||
@kindex C-c C-c
|
||
When the cursor is in a headline, this does the same as
|
||
@kbd{C-c C-q}.
|
||
@end table
|
||
|
||
@vindex org-tag-alist
|
||
Org supports tag insertion based on a @emph{list of tags}. By default this
|
||
list is constructed dynamically, containing all tags currently used in
|
||
the buffer. You may also globally specify a hard list of tags with
|
||
the variable @code{org-tag-alist}. Finally you can set the default tags
|
||
for a given file with lines like
|
||
|
||
@cindex @samp{TAGS}, keyword
|
||
@example
|
||
#+TAGS: @@work @@home @@tennisclub
|
||
#+TAGS: laptop car pc sailboat
|
||
@end example
|
||
|
||
If you have globally defined your preferred set of tags using the
|
||
variable @code{org-tag-alist}, but would like to use a dynamic tag list in
|
||
a specific file, add an empty @samp{TAGS} keyword to that file:
|
||
|
||
@example
|
||
#+TAGS:
|
||
@end example
|
||
|
||
@vindex org-tag-persistent-alist
|
||
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 @samp{TAGS}
|
||
keyword, then you may specify a list of tags with the variable
|
||
@code{org-tag-persistent-alist}. You may turn this off on a per-file basis
|
||
by adding a @samp{STARTUP} keyword to that file:
|
||
|
||
@example
|
||
#+STARTUP: noptag
|
||
@end example
|
||
|
||
By default Org mode uses the standard minibuffer completion facilities
|
||
for entering tags. However, it also implements another, quicker, tag
|
||
selection method called @emph{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
|
||
@code{org-tag-alist} in your Emacs init file. For example, you may find
|
||
the need to tag many items in different files with @samp{@@home}. In this
|
||
case you can set something like:
|
||
|
||
@lisp
|
||
(setq org-tag-alist '(("@@work" . ?w) ("@@home" . ?h) ("laptop" . ?l)))
|
||
@end lisp
|
||
|
||
@noindent
|
||
If the tag is only relevant to the file you are working on, then you
|
||
can instead set the @samp{TAGS} keyword as:
|
||
|
||
@example
|
||
#+TAGS: @@work(w) @@home(h) @@tennisclub(t) laptop(l) pc(p)
|
||
@end example
|
||
|
||
@noindent
|
||
The tags interface shows the available tags in a splash window. If
|
||
you want to start a new line after a specific tag, insert @samp{\n} into
|
||
the tag list
|
||
|
||
@example
|
||
#+TAGS: @@work(w) @@home(h) @@tennisclub(t) \n laptop(l) pc(p)
|
||
@end example
|
||
|
||
@noindent
|
||
or write them in two lines:
|
||
|
||
@example
|
||
#+TAGS: @@work(w) @@home(h) @@tennisclub(t)
|
||
#+TAGS: laptop(l) pc(p)
|
||
@end example
|
||
|
||
@noindent
|
||
You can also group together tags that are mutually exclusive by using
|
||
braces, as in:
|
||
|
||
@example
|
||
#+TAGS: @{ @@work(w) @@home(h) @@tennisclub(t) @} laptop(l) pc(p)
|
||
@end example
|
||
|
||
@noindent
|
||
you indicate that at most one of @samp{@@work}, @samp{@@home}, and @samp{@@tennisclub}
|
||
should be selected. Multiple such groups are allowed.
|
||
|
||
@noindent
|
||
Do not forget to press @kbd{C-c C-c} with the cursor in one of
|
||
these lines to activate any changes.
|
||
|
||
@noindent
|
||
To set these mutually exclusive groups in the variable
|
||
@code{org-tags-alist}, you must use the dummy tags @code{:startgroup} and
|
||
@code{:endgroup} instead of the braces. Similarly, you can use @code{:newline}
|
||
to indicate a line break. The previous example would be set globally
|
||
by the following configuration:
|
||
|
||
@lisp
|
||
(setq org-tag-alist '((:startgroup . nil)
|
||
("@@work" . ?w) ("@@home" . ?h)
|
||
("@@tennisclub" . ?t)
|
||
(:endgroup . nil)
|
||
("laptop" . ?l) ("pc" . ?p)))
|
||
@end lisp
|
||
|
||
If at least one tag has a selection key then pressing @kbd{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@footnote{Keys are automatically assigned to tags that have no
|
||
configured keys.}.
|
||
|
||
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:
|
||
|
||
@table @asis
|
||
@item @kbd{@key{TAB}}
|
||
@kindex 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. You can also add several tags: just separate them with
|
||
a comma.
|
||
|
||
@item @kbd{@key{SPC}}
|
||
@kindex SPC
|
||
Clear all tags for this line.
|
||
|
||
@item @kbd{@key{RET}}
|
||
@kindex RET
|
||
Accept the modified set.
|
||
|
||
@item @kbd{C-g}
|
||
@kindex C-g
|
||
Abort without installing changes.
|
||
|
||
@item @kbd{q}
|
||
@kindex q
|
||
If @kbd{q} is not assigned to a tag, it aborts like
|
||
@kbd{C-g}.
|
||
|
||
@item @kbd{!}
|
||
@kindex !
|
||
Turn off groups of mutually exclusive tags. Use this to (as an
|
||
exception) assign several tags from such a group.
|
||
|
||
@item @kbd{C-c}
|
||
@kindex C-c C-c
|
||
Toggle auto-exit after the next change (see below). If you are
|
||
using expert mode, the first @kbd{C-c} displays the
|
||
selection window.
|
||
@end table
|
||
|
||
@noindent
|
||
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
|
||
@samp{@@home}, @samp{laptop} and @samp{pc} tags with just the following keys:
|
||
@kbd{C-c C-c @key{SPC} h l p @key{RET}}. Switching from @samp{@@home} to @samp{@@work}
|
||
would be done with @kbd{C-c C-c w @key{RET}} or alternatively with
|
||
@kbd{C-c C-c C-c w}. Adding the non-predefined tag @samp{Sarah} could
|
||
be done with @kbd{C-c C-c @key{TAB} S a r a h @key{RET}}.
|
||
|
||
@vindex org-fast-tag-selection-single-key
|
||
If you find that most of the time you need only a single key press to
|
||
modify your list of tags, set the variable
|
||
@code{org-fast-tag-selection-single-key}. Then you no longer have to press
|
||
@kbd{@key{RET}} to exit fast tag selection---it exits after the first
|
||
change. If you then occasionally need more keys, press @kbd{C-c}
|
||
to turn off auto-exit for the current tag selection process (in
|
||
effect: start selection with @kbd{C-c C-c C-c} instead of
|
||
@kbd{C-c C-c}). If you set the variable to the value @code{expert},
|
||
the special window is not even shown for single-key tag selection, it
|
||
comes up only when you press an extra @kbd{C-c}.
|
||
|
||
@node Tag Hierarchy
|
||
@section Tag Hierarchy
|
||
|
||
@cindex group tags
|
||
@cindex tags, groups
|
||
@cindex tags hierarchy
|
||
|
||
Tags can be defined in hierarchies. A tag can be defined as a @emph{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:
|
||
|
||
@example
|
||
#+TAGS: [ GTD : Control Persp ]
|
||
@end example
|
||
|
||
In this example, @samp{GTD} is the group tag and it is related to two other
|
||
tags: @samp{Control}, @samp{Persp}. Defining @samp{Control} and @samp{Persp} as group
|
||
tags creates an hierarchy of tags:
|
||
|
||
@example
|
||
#+TAGS: [ Control : Context Task ]
|
||
#+TAGS: [ Persp : Vision Goal AOF Project ]
|
||
@end example
|
||
|
||
That can conceptually be seen as a hierarchy of tags:
|
||
|
||
@itemize
|
||
@item
|
||
@samp{GTD}
|
||
@itemize
|
||
@item
|
||
@samp{Persp}
|
||
@itemize
|
||
@item
|
||
@samp{Vision}
|
||
@item
|
||
@samp{Goal}
|
||
@item
|
||
@samp{AOF}
|
||
@item
|
||
@samp{Project}
|
||
@end itemize
|
||
@item
|
||
@samp{Control}
|
||
@itemize
|
||
@item
|
||
@samp{Context}
|
||
@item
|
||
@samp{Task}
|
||
@end itemize
|
||
@end itemize
|
||
@end itemize
|
||
|
||
You can use the @code{:startgrouptag}, @code{:grouptags} and @code{:endgrouptag}
|
||
keyword directly when setting @code{org-tag-alist} directly:
|
||
|
||
@lisp
|
||
(setq org-tag-alist '((:startgrouptag)
|
||
("GTD")
|
||
(:grouptags)
|
||
("Control")
|
||
("Persp")
|
||
(:endgrouptag)
|
||
(:startgrouptag)
|
||
("Control")
|
||
(:grouptags)
|
||
("Context")
|
||
("Task")
|
||
(:endgrouptag)))
|
||
@end lisp
|
||
|
||
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.
|
||
|
||
@example
|
||
#+TAGS: @{ Context : @@Home @@Work @@Call @}
|
||
@end example
|
||
|
||
When setting @code{org-tag-alist} you can use @code{:startgroup} and @code{:endgroup}
|
||
instead of @code{:startgrouptag} and @code{: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. The regular expressions in the group must be specified
|
||
within curly brackets. Here is an expanded example:
|
||
|
||
@example
|
||
#+TAGS: [ Vision : @{V@@.+@} ]
|
||
#+TAGS: [ Goal : @{G@@.+@} ]
|
||
#+TAGS: [ AOF : @{AOF@@.+@} ]
|
||
#+TAGS: [ Project : @{P@@.+@} ]
|
||
@end example
|
||
|
||
Searching for the tag @samp{Project} now lists all tags also including
|
||
regular expression matches for @samp{P@@.+}, and similarly for tag searches
|
||
on @samp{Vision}, @samp{Goal} and @samp{AOF}. For example, this would work well for
|
||
a project tagged with a common project-identifier,
|
||
e.g. @samp{P@@2014_OrgTags}.
|
||
|
||
@kindex C-c C-x q
|
||
@findex org-toggle-tags-groups
|
||
@vindex org-group-tags
|
||
If you want to ignore group tags temporarily, toggle group tags
|
||
support with @code{org-toggle-tags-groups}, bound to @kbd{C-c C-x q}.
|
||
If you want to disable tag groups completely, set @code{org-group-tags} to
|
||
@code{nil}.
|
||
|
||
@node Tag Searches
|
||
@section Tag Searches
|
||
|
||
@cindex tag searches
|
||
@cindex searching for tags
|
||
|
||
Once a system of tags has been set up, it can be used to collect
|
||
related information into special lists.
|
||
|
||
@table @asis
|
||
@item @kbd{C-c / m} or @kbd{C-c \} (@code{org-match-sparse-tree})
|
||
@kindex C-c / m
|
||
@kindex C-c \
|
||
@findex org-match-sparse-tree
|
||
Create a sparse tree with all headlines matching a tags search.
|
||
With a @kbd{C-u} prefix argument, ignore headlines that are
|
||
not a TODO line.
|
||
|
||
@item @kbd{C-c a m} (@code{org-tags-view})
|
||
@kindex C-c a m
|
||
@findex org-tags-view
|
||
Create a global list of tag matches from all agenda files. See
|
||
@ref{Matching tags and properties}.
|
||
|
||
@item @kbd{C-c a M} (@code{org-tags-view})
|
||
@kindex C-c a M
|
||
@vindex org-tags-match-list-sublevels
|
||
Create a global list of tag matches from all agenda files, but
|
||
check only TODO items and force checking subitems (see the option
|
||
@code{org-tags-match-list-sublevels}).
|
||
@end table
|
||
|
||
These commands all prompt for a match string which allows basic
|
||
Boolean logic like @samp{+boss+urgent-project1}, to find entries with tags
|
||
@samp{boss} and @samp{urgent}, but not @samp{project1}, or @samp{Kathy|Sally} to find
|
||
entries which are tagged, like @samp{Kathy} or @samp{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 @ref{Matching tags and properties}.
|
||
|
||
@node Properties and Columns
|
||
@chapter Properties and Columns
|
||
|
||
@cindex properties
|
||
|
||
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 every entry in an Org file.
|
||
|
||
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 @samp{release_1}, @samp{release_2}, you
|
||
can use a property, say @samp{Release}, that in different subtrees has
|
||
different values, such as @samp{1.0} or @samp{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
|
||
@ref{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.
|
||
@end menu
|
||
|
||
@node Property Syntax
|
||
@section Property Syntax
|
||
|
||
@cindex property syntax
|
||
@cindex drawer, for properties
|
||
|
||
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 @ref{Drawers}) with the name @samp{PROPERTIES}, which has to be
|
||
located right below a headline, and its planning line (see @ref{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:
|
||
|
||
@example
|
||
* CD collection
|
||
** Classic
|
||
*** Goldberg Variations
|
||
:PROPERTIES:
|
||
:Title: Goldberg Variations
|
||
:Composer: J.S. Bach
|
||
:Artist: Glen Gould
|
||
:Publisher: Deutsche Grammophon
|
||
:NDisks: 1
|
||
:END:
|
||
@end example
|
||
|
||
Depending on the value of @code{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 @ref{Property Inheritance}.
|
||
|
||
You may define the allowed values for a particular property @samp{Xyz} by
|
||
setting a property @samp{Xyz_ALL}. This special property is @emph{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:
|
||
|
||
@example
|
||
* CD collection
|
||
:PROPERTIES:
|
||
:NDisks_ALL: 1 2 3 4
|
||
:Publisher_ALL: "Deutsche Grammophon" Philips EMI
|
||
:END:
|
||
@end example
|
||
|
||
If you want to set properties that can be inherited by any entry in
|
||
a file, use a line like:
|
||
|
||
@cindex @samp{_ALL} suffix, in properties
|
||
@cindex @samp{PROPERTY}, keyword
|
||
@example
|
||
#+PROPERTY: NDisks_ALL 1 2 3 4
|
||
@end example
|
||
|
||
@cindex @samp{+} suffix, in properties
|
||
If you want to add to the value of an existing property, append a @samp{+}
|
||
to the property name. The following results in the property @samp{var}
|
||
having the value @samp{foo=1 bar=2}.
|
||
|
||
@example
|
||
#+PROPERTY: var foo=1
|
||
#+PROPERTY: var+ bar=2
|
||
@end example
|
||
|
||
It is also possible to add to the values of inherited properties. The
|
||
following results in the @samp{Genres} property having the value @samp{Classic
|
||
Baroque} under the @samp{Goldberg Variations} subtree.
|
||
|
||
@example
|
||
* CD collection
|
||
** Classic
|
||
:PROPERTIES:
|
||
:Genres: Classic
|
||
:END:
|
||
*** Goldberg Variations
|
||
:PROPERTIES:
|
||
:Title: Goldberg Variations
|
||
:Composer: J.S. Bach
|
||
:Artist: Glen Gould
|
||
:Publisher: Deutsche Grammophon
|
||
:NDisks: 1
|
||
:Genres+: Baroque
|
||
:END:
|
||
@end example
|
||
|
||
Note that a property can only have one entry per drawer.
|
||
|
||
@vindex org-global-properties
|
||
Property values set with the global variable @code{org-global-properties}
|
||
can be inherited by all entries in all Org files.
|
||
|
||
@noindent
|
||
The following commands help to work with properties:
|
||
|
||
@table @asis
|
||
@item @kbd{M-@key{TAB}} (@code{pcomplete})
|
||
@kindex M-TAB
|
||
@findex pcomplete
|
||
After an initial colon in a line, complete property keys. All
|
||
keys used in the current file are offered as possible
|
||
completions.
|
||
|
||
@item @kbd{C-c C-x p} (@code{org-set-property})
|
||
@kindex C-c C-x p
|
||
@findex org-set-property
|
||
Set a property. This prompts for a property name and a value.
|
||
If necessary, the property drawer is created as well.
|
||
|
||
@item @kbd{C-u M-x org-insert-drawer}
|
||
@findex 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.
|
||
|
||
@item @kbd{C-c C-c} (@code{org-property-action})
|
||
@kindex C-c C-c
|
||
@findex org-property-action
|
||
With the cursor in a property drawer, this executes property
|
||
commands.
|
||
|
||
@item @kbd{C-c C-c s} (@code{org-set-property})
|
||
@kindex C-c C-c s
|
||
@findex org-set-property
|
||
Set a property in the current entry. Both the property and the value
|
||
can be inserted using completion.
|
||
|
||
@item @kbd{S-@key{RIGHT}} (@code{org-property-next-allowed-values})
|
||
@itemx @kbd{S-@key{LEFT}} (@code{org-property-previous-allowed-value})
|
||
@kindex S-RIGHT
|
||
@kindex S-LEFT
|
||
Switch property at point to the next/previous allowed value.
|
||
|
||
@item @kbd{C-c C-c d} (@code{org-delete-property})
|
||
@kindex C-c C-c d
|
||
@findex org-delete-property
|
||
Remove a property from the current entry.
|
||
|
||
@item @kbd{C-c C-c D} (@code{org-delete-property-globally})
|
||
@kindex C-c C-c D
|
||
@findex org-delete-property-globally
|
||
Globally remove a property, from all entries in the current file.
|
||
|
||
@item @kbd{C-c C-c c} (@code{org-compute-property-at-point})
|
||
@kindex C-c C-c c
|
||
@findex org-compute-property-at-point
|
||
Compute the property at point, using the operator and scope from
|
||
the nearest column format definition.
|
||
@end table
|
||
|
||
@node Special Properties
|
||
@section Special Properties
|
||
|
||
@cindex properties, special
|
||
|
||
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 @ref{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:
|
||
|
||
@cindex @samp{ALLTAGS}, special property
|
||
@cindex @samp{BLOCKED}, special property
|
||
@cindex @samp{CLOCKSUM}, special property
|
||
@cindex @samp{CLOCKSUM_T}, special property
|
||
@cindex @samp{CLOSED}, special property
|
||
@cindex @samp{DEADLINE}, special property
|
||
@cindex @samp{FILE}, special property
|
||
@cindex @samp{ITEM}, special property
|
||
@cindex @samp{PRIORITY}, special property
|
||
@cindex @samp{SCHEDULED}, special property
|
||
@cindex @samp{TAGS}, special property
|
||
@cindex @samp{TIMESTAMP}, special property
|
||
@cindex @samp{TIMESTAMP_IA}, special property
|
||
@cindex @samp{TODO}, special property
|
||
@multitable {aaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
|
||
@item @samp{ALLTAGS}
|
||
@tab All tags, including inherited ones.
|
||
@item @samp{BLOCKED}
|
||
@tab @code{t} if task is currently blocked by children or siblings.
|
||
@item @samp{CATEGORY}
|
||
@tab The category of an entry.
|
||
@item @samp{CLOCKSUM}
|
||
@tab The sum of CLOCK intervals in the subtree. @code{org-clock-sum}
|
||
@item
|
||
@tab must be run first to compute the values in the current buffer.
|
||
@item @samp{CLOCKSUM_T}
|
||
@tab The sum of CLOCK intervals in the subtree for today.
|
||
@item
|
||
@tab @code{org-clock-sum-today} must be run first to compute the
|
||
@item
|
||
@tab values in the current buffer.
|
||
@item @samp{CLOSED}
|
||
@tab When was this entry closed?
|
||
@item @samp{DEADLINE}
|
||
@tab The deadline time string, without the angular brackets.
|
||
@item @samp{FILE}
|
||
@tab The filename the entry is located in.
|
||
@item @samp{ITEM}
|
||
@tab The headline of the entry.
|
||
@item @samp{PRIORITY}
|
||
@tab The priority of the entry, a string with a single letter.
|
||
@item @samp{SCHEDULED}
|
||
@tab The scheduling timestamp, without the angular brackets.
|
||
@item @samp{TAGS}
|
||
@tab The tags defined directly in the headline.
|
||
@item @samp{TIMESTAMP}
|
||
@tab The first keyword-less timestamp in the entry.
|
||
@item @samp{TIMESTAMP_IA}
|
||
@tab The first inactive timestamp in the entry.
|
||
@item @samp{TODO}
|
||
@tab The TODO keyword of the entry.
|
||
@end multitable
|
||
|
||
@node Property Searches
|
||
@section Property Searches
|
||
|
||
@cindex properties, searching
|
||
@cindex searching, of properties
|
||
|
||
To create sparse trees and special lists with selection based on
|
||
properties, the same commands are used as for tag searches (see @ref{Tag Searches}).
|
||
|
||
@table @asis
|
||
@item @kbd{C-c / m} or @kbd{C-c \} (@code{org-match-sparse-tree})
|
||
@kindex C-c / m
|
||
@kindex C-c \
|
||
@findex org-match-sparse-tree
|
||
Create a sparse tree with all matching entries. With
|
||
a @kbd{C-u} prefix argument, ignore headlines that are not
|
||
a TODO line.
|
||
|
||
@item @kbd{C-c a m}, @code{org-tags-view}
|
||
@kindex C-c a m
|
||
Create a global list of tag/property matches from all agenda
|
||
files.
|
||
|
||
@item @kbd{C-c a M} (@code{org-tags-view})
|
||
@kindex C-c a M
|
||
@findex org-tags-view
|
||
@vindex org-tags-match-list-sublevels
|
||
Create a global list of tag matches from all agenda files, but
|
||
check only TODO items and force checking of subitems (see the
|
||
option @code{org-tags-match-list-sublevels}).
|
||
@end table
|
||
|
||
The syntax for the search string is described in @ref{Matching tags and properties}.
|
||
|
||
There is also a special command for creating sparse trees based on a
|
||
single property:
|
||
|
||
@table @asis
|
||
@item @kbd{C-c / p}
|
||
@kindex 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.
|
||
@end table
|
||
|
||
@node Property Inheritance
|
||
@section Property Inheritance
|
||
|
||
@cindex properties, inheritance
|
||
@cindex inheritance, of properties
|
||
|
||
@vindex org-use-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
|
||
@code{org-use-property-inheritance}. It may be set to @code{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 @code{nil}, this is interpreted as
|
||
an explicit un-define of the property, so that inheritance search
|
||
stops at this value and returns @code{nil}.
|
||
|
||
Org mode has a few properties for which inheritance is hard-coded, at
|
||
least for the special applications for which they are used:
|
||
|
||
@table @asis
|
||
@item @code{COLUMNS}
|
||
@cindex @samp{COLUMNS}, property
|
||
The @samp{COLUMNS} property defines the format of column view (see
|
||
@ref{Column View}). It is inherited in the sense that the level where
|
||
a @samp{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.
|
||
|
||
@item @code{CATEGORY}
|
||
@cindex @samp{CATEGORY}, property
|
||
For agenda view, a category set through a @samp{CATEGORY} property
|
||
applies to the entire subtree.
|
||
|
||
@item @code{ARCHIVE}
|
||
@cindex @samp{ARCHIVE}, property
|
||
For archiving, the @samp{ARCHIVE} property may define the archive
|
||
location for the entire subtree (see @ref{Moving subtrees}).
|
||
|
||
@item @code{LOGGING}
|
||
@cindex @samp{LOGGING}, property
|
||
The @samp{LOGGING} property may define logging settings for an entry
|
||
or a subtree (see @ref{Tracking TODO state changes}).
|
||
@end table
|
||
|
||
@node Column View
|
||
@section Column View
|
||
|
||
A great way to view and edit properties in an outline tree is @emph{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---@kbd{S-@key{TAB}} @kbd{S-@key{TAB}}, or simply @kbd{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
|
||
@ref{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.
|
||
@end menu
|
||
|
||
@node Defining columns
|
||
@subsection Defining columns
|
||
|
||
@cindex column view, for properties
|
||
@cindex properties, column view
|
||
|
||
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.
|
||
@end menu
|
||
|
||
@node Scope of column definitions
|
||
@subsubsection Scope of column definitions
|
||
|
||
To define a column format for an entire file, use a line like:
|
||
|
||
@cindex @samp{COLUMNS}, keyword
|
||
@example
|
||
#+COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
|
||
@end example
|
||
|
||
To specify a format that only applies to a specific tree, add
|
||
a @samp{COLUMNS} property to the top node of that tree, for example:
|
||
|
||
@example
|
||
** Top node for columns view
|
||
:PROPERTIES:
|
||
:COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
|
||
:END:
|
||
@end example
|
||
|
||
If a @samp{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.
|
||
|
||
@node Column attributes
|
||
@subsubsection Column attributes
|
||
|
||
A column definition sets the attributes of a column. The general
|
||
definition looks like this:
|
||
|
||
@example
|
||
%[WIDTH]PROPERTY[(TITLE)][@{SUMMARY-TYPE@}]
|
||
@end example
|
||
|
||
@noindent
|
||
Except for the percent sign and the property name, all items are
|
||
optional. The individual parts have the following meaning:
|
||
|
||
@table @asis
|
||
@item @var{WIDTH}
|
||
An integer specifying the width of the column in characters. If
|
||
omitted, the width is determined automatically.
|
||
|
||
@item @var{PROPERTY}
|
||
The property that should be edited in this column. Special
|
||
properties representing meta data are allowed here as well (see
|
||
@ref{Special Properties}).
|
||
|
||
@item @var{TITLE}
|
||
The header text for the column. If omitted, the property name is
|
||
used.
|
||
|
||
@item @var{SUMMARY-TYPE}
|
||
The summary type. If specified, the column values for parent
|
||
nodes are computed from the children@footnote{If more than one summary type applies to the same property,
|
||
the parent values are computed according to the first of them.}.
|
||
|
||
Supported summary types are:
|
||
|
||
@multitable {aaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
|
||
@item @samp{+}
|
||
@tab Sum numbers in this column.
|
||
@item @samp{+;%.1f}
|
||
@tab Like @samp{+}, but format result with @samp{%.1f}.
|
||
@item @samp{$}
|
||
@tab Currency, short for @samp{+;%.2f}.
|
||
@item @samp{min}
|
||
@tab Smallest number in column.
|
||
@item @samp{max}
|
||
@tab Largest number.
|
||
@item @samp{mean}
|
||
@tab Arithmetic mean of numbers.
|
||
@item @samp{X}
|
||
@tab Checkbox status, @samp{[X]} if all children are @samp{[X]}.
|
||
@item @samp{X/}
|
||
@tab Checkbox status, @samp{[n/m]}.
|
||
@item @samp{X%}
|
||
@tab Checkbox status, @samp{[n%]}.
|
||
@item @samp{:}
|
||
@tab Sum times, HH:MM, plain numbers are hours.
|
||
@item @samp{:min}
|
||
@tab Smallest time value in column.
|
||
@item @samp{:max}
|
||
@tab Largest time value.
|
||
@item @samp{:mean}
|
||
@tab Arithmetic mean of time values.
|
||
@item @samp{@@min}
|
||
@tab Minimum age@footnote{An age is defined as a duration, using effort modifiers
|
||
defined in @code{org-effort-durations}, e.g., @samp{3d 1h}. If any value in the
|
||
column is as such, the summary is also an effort duration.} (in days/hours/mins/seconds).
|
||
@item @samp{@@max}
|
||
@tab Maximum age (in days/hours/mins/seconds).
|
||
@item @samp{@@mean}
|
||
@tab Arithmetic mean of ages (in days/hours/mins/seconds).
|
||
@item @samp{est+}
|
||
@tab Add low-high estimates.
|
||
@end multitable
|
||
|
||
@noindent
|
||
@vindex org-columns-summary-types
|
||
You can also define custom summary types by setting
|
||
@code{org-columns-summary-types}.
|
||
@end table
|
||
|
||
The @samp{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, @samp{est+} adds
|
||
the statistical mean and variance of the sub-tasks, 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, @samp{est+} estimates the full job more realistically, at 10--15
|
||
days.
|
||
|
||
Here is an example for a complete columns definition, along with
|
||
allowed values@footnote{Please note that the @samp{COLUMNS} definition must be on a single
|
||
line; it is wrapped here only because of formatting constraints.}.
|
||
|
||
@example
|
||
: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]"
|
||
@end example
|
||
|
||
@noindent
|
||
The first column, @samp{%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 @samp{ITEM} specifier. The other specifiers
|
||
create columns @samp{Owner} with a list of names as allowed values, for
|
||
@samp{Status} with four different possible values, and for a checkbox field
|
||
@samp{Approved}. When no width is given after the @samp{%} character, the
|
||
column is exactly as wide as it needs to be in order to fully display
|
||
all values. The @samp{Approved} column does have a modified title
|
||
(@samp{Approved?}, with a question mark). Summaries are created for the
|
||
@samp{Time_Estimate} column by adding time duration expressions like HH:MM,
|
||
and for the @samp{Approved} column, by providing an @samp{[X]} status if all
|
||
children have been checked. The @samp{CLOCKSUM} and @samp{CLOCKSUM_T} columns
|
||
are special, they lists the sums of CLOCK intervals in the subtree,
|
||
either for all clocks or just for today.
|
||
|
||
@node Using column view
|
||
@subsection Using column view
|
||
|
||
|
||
|
||
@anchor{Turning column view on or off}
|
||
@subsubheading Turning column view on or off
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-x C-c} (@code{org-columns})
|
||
@kindex C-c C-x C-c
|
||
@vindex org-columns
|
||
@vindex org-columns-default-format
|
||
Turn on column view. If the cursor is before the first headline
|
||
in the file, column view is turned on for the entire file, using
|
||
the @samp{#+COLUMNS} definition. If the cursor is somewhere inside
|
||
the outline, this command searches the hierarchy, up from point,
|
||
for a @samp{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 @samp{COLUMNS} property. If no such
|
||
property is found, the format is taken from the @samp{#+COLUMNS} line
|
||
or from the variable @code{org-columns-default-format}, and column
|
||
view is established for the current entry and its subtree.
|
||
|
||
@item @kbd{r} or @kbd{g} (@code{org-columns-redo})
|
||
@kindex r
|
||
@kindex g
|
||
@findex org-columns-redo
|
||
Recreate the column view, to include recent changes made in the
|
||
buffer.
|
||
|
||
@item @kbd{q} (@code{org-columns-quit})
|
||
@kindex q
|
||
@findex org-columns-quit
|
||
Exit column view.
|
||
@end table
|
||
|
||
@anchor{Editing values}
|
||
@subsubheading Editing values
|
||
|
||
@table @asis
|
||
@item @kbd{@key{LEFT}}, @kbd{@key{RIGHT}}, @kbd{@key{UP}}, @kbd{@key{DOWN}}
|
||
Move through the column view from field to field.
|
||
|
||
@item @kbd{1..9,0}
|
||
@kindex 1..9,0
|
||
Directly select the Nth allowed value, @kbd{0} selects the
|
||
10th value.
|
||
|
||
@item @kbd{n} or @kbd{S-@key{RIGHT}} (@code{org-columns-next-allowed-value})
|
||
@itemx @kbd{p} or @kbd{S-@key{LEFT}} (@code{org-columns-previous-allowed-value})
|
||
@kindex n
|
||
@kindex S-RIGHT
|
||
@kindex p
|
||
@kindex S-LEFT
|
||
@findex org-columns-next-allowed-value
|
||
@findex 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.
|
||
|
||
@item @kbd{e} (@code{org-columns-edit-value})
|
||
@kindex e
|
||
@findex 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 @samp{TAGS} property.
|
||
|
||
@item @kbd{C-c C-c} (@code{org-columns-set-tags-or-toggle})
|
||
@kindex C-c C-c
|
||
@findex org-columns-set-tags-or-toggle
|
||
When there is a checkbox at point, toggle it.
|
||
|
||
@item @kbd{v} (@code{org-columns-show-value})
|
||
@kindex v
|
||
@findex 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.
|
||
|
||
@item @kbd{a} (@code{org-columns-edit-allowed})
|
||
@kindex a
|
||
@findex 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.
|
||
@end table
|
||
|
||
@anchor{Modifying column view on-the-fly}
|
||
@subsubheading Modifying column view on-the-fly:
|
||
|
||
@table @asis
|
||
@item @kbd{<} (@code{org-columns-narrow})
|
||
@itemx @kbd{>} (@code{org-columns-widen})
|
||
@kindex <
|
||
@kindex >
|
||
@findex org-columns-narrow
|
||
@findex org-columns-widen
|
||
Make the column narrower/wider by one character.
|
||
|
||
@item @kbd{S-M-@key{RIGHT}} (@code{org-columns-new})
|
||
@kindex S-M-RIGHT
|
||
@findex org-columns-new
|
||
Insert a new column, to the left of the current column.
|
||
|
||
@item @kbd{S-M-@key{LEFT}} (@code{org-columns-delete})
|
||
@kindex S-M-LEFT
|
||
@findex org-columns-delete
|
||
Delete the current column.
|
||
@end table
|
||
|
||
@node Capturing column view
|
||
@subsection 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 @samp{columnview} dynamic block (see @ref{Dynamic Blocks}). The frame of
|
||
this block looks like this:
|
||
|
||
@cindex @samp{BEGIN columnview}
|
||
@example
|
||
* The column view
|
||
#+BEGIN: columnview :hlines 1 :id "label"
|
||
|
||
#+END:
|
||
@end example
|
||
|
||
@noindent
|
||
This dynamic block has the following parameters:
|
||
|
||
@table @asis
|
||
@item @samp{: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:
|
||
|
||
@table @asis
|
||
@item @samp{local}
|
||
Use the tree in which the capture block is located.
|
||
|
||
@item @samp{global}
|
||
Make a global view, including all headings in the file.
|
||
|
||
@item @samp{file:FILENAME}
|
||
Run column view at the top of the @var{FILENAME} file
|
||
|
||
@item @samp{LABEL}
|
||
@cindex @samp{ID}, property
|
||
Call column view in the tree that has an @samp{ID} property with
|
||
the value @var{LABEL}. You can use @kbd{M-x org-id-copy} to create a globally unique ID for the
|
||
current entry and copy it to the kill-ring.
|
||
@end table
|
||
|
||
@item @samp{:hlines}
|
||
When @code{t}, insert an hline after every line. When a number N,
|
||
insert an hline before each headline with level @code{<= N}.
|
||
|
||
@item @samp{:vlines}
|
||
When non-@code{nil}, force column groups to get vertical lines.
|
||
|
||
@item @samp{:maxlevel}
|
||
When set to a number, do not capture entries below this level.
|
||
|
||
@item @samp{:skip-empty-rows}
|
||
When non-@code{nil}, skip rows where the only non-empty specifier of
|
||
the column view is @samp{ITEM}.
|
||
|
||
@item @samp{:indent}
|
||
When non-@code{nil}, indent each @samp{ITEM} field according to its level.
|
||
@end table
|
||
|
||
@noindent
|
||
The following commands insert or update the dynamic block:
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-x i} (@code{org-insert-columns-dblock})
|
||
@kindex C-c C-x i
|
||
@findex org-insert-columns-dblock
|
||
Insert a dynamic block capturing a column view. Prompt for the
|
||
scope or ID of the view.
|
||
|
||
@item @kbd{C-c C-c} @kbd{C-c C-x C-u} (@code{org-dblock-update})
|
||
@kindex C-c C-c
|
||
@kindex C-c C-x C-u
|
||
@findex org-dblock-update
|
||
Update dynamic block at point. The cursor needs to be in the
|
||
@samp{#+BEGIN} line of the dynamic block.
|
||
|
||
@item @kbd{C-u C-c C-x C-u} (@code{org-update-all-dblocks})
|
||
@kindex C-u C-c C-x C-u
|
||
Update all dynamic blocks (see @ref{Dynamic Blocks}). This is useful
|
||
if you have several clock table blocks, column-capturing blocks
|
||
or other dynamic blocks in a buffer.
|
||
@end table
|
||
|
||
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 @samp{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 @samp{org-collector.el} which is
|
||
a contributed package@footnote{Contributed packages are not part of Emacs, but are
|
||
distributed with the main distribution of Org---visit
|
||
@uref{https://orgmode.org}.}. 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.
|
||
|
||
@node Dates and Times
|
||
@chapter Dates and Times
|
||
|
||
@cindex dates
|
||
@cindex times
|
||
@cindex timestamp
|
||
@cindex date stamp
|
||
|
||
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 @emph{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.
|
||
@end menu
|
||
|
||
@node Timestamps
|
||
@section Timestamps, Deadlines and Scheduling
|
||
|
||
@cindex timestamps
|
||
@cindex ranges, time
|
||
@cindex date stamps
|
||
@cindex deadlines
|
||
@cindex scheduling
|
||
|
||
A timestamp is a specification of a date (possibly with a time or
|
||
a range of times) in a special format, either @samp{<2003-09-16 Tue>} or
|
||
@samp{<2003-09-16 Tue 09:39>} or @samp{<2003-09-16 Tue 12:00-12:30>}@footnote{The Org date format is inspired by the standard ISO 8601
|
||
date/time format. To use an alternative format, see @ref{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.}.
|
||
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 @ref{Weekly/daily agenda}). We distinguish:
|
||
|
||
@table @asis
|
||
@item Plain timestamp; Event; Appointment
|
||
@cindex timestamp
|
||
@cindex 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 timeline and agenda displays, the headline of an entry
|
||
associated with a plain timestamp is shown exactly on that date.
|
||
|
||
@example
|
||
* Meet Peter at the movies
|
||
<2006-11-01 Wed 19:15>
|
||
* Discussion on climate change
|
||
<2006-11-02 Thu 20:00-22:00>
|
||
@end example
|
||
|
||
@item Timestamp with repeater interval
|
||
@cindex timestamp, with repeater interval
|
||
A timestamp may contain a @emph{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:
|
||
|
||
@example
|
||
* Pick up Sam at school
|
||
<2007-05-16 Wed 12:30 +1w>
|
||
@end example
|
||
|
||
@item Diary-style sexp entries
|
||
@cindex diary style timestamps
|
||
@cindex sexp timestamps
|
||
For more complex date specifications, Org mode supports using the
|
||
special sexp diary entries implemented in the Emacs
|
||
calendar/diary package@footnote{When working with the standard diary sexp functions, you need
|
||
to be very careful with the order of the arguments. That order
|
||
depends evilly on the variable @code{calendar-date-style}. For example, to
|
||
specify a date December 12, 2005, the call might look like
|
||
@samp{(diary-date 12 1 2005)} or @samp{(diary-date 1 12 2005)} or @samp{(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 @code{org-date} or @code{org-anniversary}. These work just
|
||
like the corresponding @code{diary-} functions, but with stable ISO order
|
||
of arguments (year, month, day) wherever applicable, independent of
|
||
the value of @code{calendar-date-style}.}. For example, with optional time:
|
||
|
||
@example
|
||
* 22:00-23:00 The nerd meeting on every 2nd Thursday of the month
|
||
<%%(org-float t 4 2)>
|
||
@end example
|
||
|
||
@item Time/Date range
|
||
@cindex timerange
|
||
@cindex date range
|
||
Two timestamps connected by @samp{--} 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:
|
||
|
||
@example
|
||
** Meeting in Amsterdam
|
||
<2004-08-23 Mon>--<2004-08-26 Thu>
|
||
@end example
|
||
|
||
@item Inactive timestamp
|
||
@cindex timestamp, inactive
|
||
@cindex 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 @emph{not} trigger an entry to show up in the agenda.
|
||
|
||
@example
|
||
* Gillian comes late for the fifth time
|
||
[2006-11-01 Wed]
|
||
@end example
|
||
@end table
|
||
|
||
@node Creating Timestamps
|
||
@section 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.
|
||
|
||
@table @asis
|
||
@item @kbd{C-c .} (@code{org-time-stamp})
|
||
@kindex C-c .
|
||
@findex org-time-stamp
|
||
Prompt for a date and insert a corresponding timestamp. When the
|
||
cursor 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.
|
||
|
||
@kindex C-u C-c .
|
||
@vindex org-time-stamp-rounding-minutes
|
||
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
|
||
@code{org-time-stamp-rounding-minutes}.
|
||
|
||
@kindex C-u C-u C-c .
|
||
With two prefix arguments, insert an active timestamp with the
|
||
current time without prompting.
|
||
|
||
@item @kbd{C-c !} (@code{org-time-stamp-inactive})
|
||
@kindex C-c !
|
||
@kindex C-u C-c !
|
||
@kindex C-u C-u C-c !
|
||
@findex org-time-stamp-inactive
|
||
Like @kbd{C-c .}, but insert an inactive timestamp that does
|
||
not cause an agenda entry.
|
||
|
||
@item @kbd{C-c C-c}
|
||
@kindex C-c C-c
|
||
Normalize timestamp, insert or fix day name if missing or wrong.
|
||
|
||
@item @kbd{C-c <} (@code{org-date-from-calendar})
|
||
@kindex C-c <
|
||
@findex org-date-from-calendar
|
||
Insert a timestamp corresponding to the cursor date in the
|
||
calendar.
|
||
|
||
@item @kbd{C-c >} (@code{org-goto-calendar})
|
||
@kindex C-c >
|
||
@findex 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.
|
||
|
||
@item @kbd{C-c C-o} (@code{org-open-at-point})
|
||
@kindex C-c C-o
|
||
@findex org-open-at-point
|
||
Access the agenda for the date given by the timestamp or -range
|
||
at point (see @ref{Weekly/daily agenda}).
|
||
|
||
@item @kbd{S-@key{LEFT}} (@code{org-timestamp-down-day})
|
||
@itemx @kbd{S-@key{RIGHT}} (@code{org-timestamp-up-day})
|
||
@kindex S-LEFT
|
||
@kindex S-RIGHT
|
||
@findex org-timestamp-down-day
|
||
@findex org-timestamp-up-day
|
||
Change date at cursor by one day. These key bindings conflict
|
||
with shift-selection and related modes (see @ref{Conflicts}).
|
||
|
||
@item @kbd{S-@key{UP}} (@code{org-timestamp-up})
|
||
@itemx @kbd{S-@key{DOWN}} (@code{org-timestamp-down})
|
||
@kindex S-UP
|
||
@kindex S-DOWN
|
||
Change the item under the cursor in a timestamp. The cursor can
|
||
be on a year, month, day, hour or minute. When the timestamp
|
||
contains a time range like @samp{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 the cursor is in a headline and not at a timestamp,
|
||
these same keys modify the priority of an item. (see
|
||
@ref{Priorities}). The key bindings also conflict with
|
||
shift-selection and related modes (see @ref{Conflicts}).
|
||
|
||
@item @kbd{C-c C-y} (@code{org-evaluate-time-range})
|
||
@kindex C-c C-y
|
||
@findex org-evaluate-time-range
|
||
@cindex 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).
|
||
@end table
|
||
|
||
@menu
|
||
* The date/time prompt:: How Org mode helps you enter dates and times.
|
||
* Custom time format:: Making dates look different.
|
||
@end menu
|
||
|
||
@node The date/time prompt
|
||
@subsection The date/time prompt
|
||
|
||
@cindex date, reading in minibuffer
|
||
@cindex time, reading in minibuffer
|
||
|
||
@vindex org-read-date-prefer-future
|
||
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 @emph{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 @emph{before} today, it assumes that you mean a future
|
||
date@footnote{See the variable @code{org-read-date-prefer-future}. You may set
|
||
that variable to the symbol @code{time} to even make a time before now
|
||
shift the date to tomorrow.}. If the date has been automatically shifted into the
|
||
future, the time prompt shows this with @samp{(=>F)}.
|
||
|
||
For example, let's assume that today is @strong{June 13, 2006}. Here is how
|
||
various inputs are interpreted, the items filled in by Org mode are in
|
||
@strong{bold}.
|
||
|
||
@multitable {aaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
|
||
@item @samp{3-2-5}
|
||
@tab @result{} 2003-02-05
|
||
@item @samp{2/5/3}
|
||
@tab @result{} 2003-02-05
|
||
@item @samp{14}
|
||
@tab @result{} @strong{2006}-@strong{06}-14
|
||
@item @samp{12}
|
||
@tab @result{} @strong{2006}-@strong{07}-12
|
||
@item @samp{2/5}
|
||
@tab @result{} @strong{2007}-02-05
|
||
@item @samp{Fri}
|
||
@tab @result{} nearest Friday (default date or later)
|
||
@item @samp{sep 15}
|
||
@tab @result{} @strong{2006}-09-15
|
||
@item @samp{feb 15}
|
||
@tab @result{} @strong{2007}-02-15
|
||
@item @samp{sep 12 9}
|
||
@tab @result{} 2009-09-12
|
||
@item @samp{12:45}
|
||
@tab @result{} @strong{2006}-@strong{06}-@strong{13} 12:45
|
||
@item @samp{22 sept 0:34}
|
||
@tab @result{} @strong{2006}-09-22 0:34
|
||
@item @samp{w4}
|
||
@tab @result{} ISO week for of the current year @strong{2006}
|
||
@item @samp{2012 w4 fri}
|
||
@tab @result{} Friday of ISO week 4 in 2012
|
||
@item @samp{2012-w04-5}
|
||
@tab @result{} Same as above
|
||
@end multitable
|
||
|
||
Furthermore you can specify a relative date by giving, as the @emph{first}
|
||
thing in the input: a plus/minus sign, a number and a letter---@samp{d},
|
||
@samp{w}, @samp{m} or @samp{y}---to indicate change in days, weeks, months, or
|
||
years. With a single plus or minus, the date is always relative to
|
||
today. 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.:
|
||
|
||
@multitable {aaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
|
||
@item @samp{+0}
|
||
@tab @result{} today
|
||
@item @samp{.}
|
||
@tab @result{} today
|
||
@item @samp{+4d}
|
||
@tab @result{} four days from today
|
||
@item @samp{+4}
|
||
@tab @result{} same as +4d
|
||
@item @samp{+2w}
|
||
@tab @result{} two weeks from today
|
||
@item @samp{++5}
|
||
@tab @result{} five days from default date
|
||
@item @samp{+2tue}
|
||
@tab @result{} second Tuesday from now
|
||
@end multitable
|
||
|
||
@vindex parse-time-months
|
||
@vindex parse-time-weekdays
|
||
The function understands English month and weekday abbreviations. If
|
||
you want to use un-abbreviated names and/or other languages, configure
|
||
the variables @code{parse-time-months} and @code{parse-time-weekdays}.
|
||
|
||
@vindex org-read-date-force-compatible-dates
|
||
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
|
||
@code{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 @samp{+} as the
|
||
separator in the latter case, e.g.:
|
||
|
||
@multitable {aaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaa}
|
||
@item @samp{11am-1:15pm}
|
||
@tab @result{} 11:00-13:15
|
||
@item @samp{11am--1:15pm}
|
||
@tab @result{} same as above
|
||
@item @samp{11am+2:15}
|
||
@tab @result{} same as above
|
||
@end multitable
|
||
|
||
@cindex calendar, for selecting date
|
||
@vindex org-popup-calendar-for-date-prompt
|
||
Parallel to the minibuffer prompt, a calendar is popped up@footnote{If you do not need/want the calendar, configure the variable
|
||
@code{org-popup-calendar-for-date-prompt}.}.
|
||
When you exit the date prompt, either by clicking on a date in the
|
||
calendar, or by pressing @kbd{@key{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:
|
||
|
||
@kindex <
|
||
@kindex >
|
||
@kindex M-v
|
||
@kindex C-v
|
||
@kindex mouse-1
|
||
@kindex S-RIGHT
|
||
@kindex S-LEFT
|
||
@kindex S-DOWN
|
||
@kindex S-UP
|
||
@kindex M-S-RIGHT
|
||
@kindex M-S-LEFT
|
||
@kindex RET
|
||
@multitable @columnfractions 0.25 0.55
|
||
@item @kbd{@key{RET}}
|
||
@tab Choose date at cursor in calendar.
|
||
@item @kbd{mouse-1}
|
||
@tab Select date by clicking on it.
|
||
@item @kbd{S-@key{RIGHT}}
|
||
@tab One day forward.
|
||
@item @kbd{S-@key{LEFT}}
|
||
@tab One day backward.
|
||
@item @kbd{S-@key{DOWN}}
|
||
@tab One week forward.
|
||
@item @kbd{S-@key{UP}}
|
||
@tab One week backward.
|
||
@item @kbd{M-S-@key{RIGHT}}
|
||
@tab One month forward.
|
||
@item @kbd{M-S-@key{LEFT}}
|
||
@tab One month backward.
|
||
@item @kbd{>}
|
||
@tab Scroll calendar forward by one month.
|
||
@item @kbd{<}
|
||
@tab Scroll calendar backward by one month.
|
||
@item @kbd{M-v}
|
||
@tab Scroll calendar forward by 3 months.
|
||
@item @kbd{C-v}
|
||
@tab Scroll calendar backward by 3 months.
|
||
@end multitable
|
||
|
||
@vindex org-read-date-display-live
|
||
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@footnote{If you find this distracting, turn off the display with
|
||
@code{org-read-date-display-live}.}.
|
||
|
||
@node Custom time format
|
||
@subsection Custom time format
|
||
|
||
@cindex custom date/time format
|
||
@cindex time format, custom
|
||
@cindex date format, custom
|
||
|
||
@vindex org-display-custom-times
|
||
@vindex org-time-stamp-custom-formats
|
||
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 @code{org-display-custom-times} and
|
||
@code{org-time-stamp-custom-formats}.
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-x C-t} (@code{org-toggle-time-stamp-overlays})
|
||
@kindex C-c C-x C-t
|
||
@findex org-toggle-time-stamp-overlays
|
||
Toggle the display of custom formats for dates and times.
|
||
@end table
|
||
|
||
@noindent
|
||
Org mode needs the default format for scanning, so the custom
|
||
date/time format does not @emph{replace} the default format. Instead, it
|
||
is put @emph{over} the default format using text properties. This has the
|
||
following consequences:
|
||
|
||
@itemize
|
||
@item
|
||
You cannot place the cursor onto a timestamp anymore, only before or
|
||
after.
|
||
|
||
@item
|
||
The @kbd{S-@key{UP}} and @kbd{S-@key{DOWN}} keys can no longer be used
|
||
to adjust each component of a timestamp. If the cursor is at the
|
||
beginning of the stamp, @kbd{S-@key{UP}} and @kbd{S-@key{DOWN}} change
|
||
the stamp by one day, just like @kbd{S-@key{LEFT}}
|
||
@kbd{S-@key{RIGHT}}. At the end of the stamp, change the time by one
|
||
minute.
|
||
|
||
@item
|
||
If the timestamp contains a range of clock times or a repeater,
|
||
these are not overlaid, but remain in the buffer as they were.
|
||
|
||
@item
|
||
When you delete a timestamp character-by-character, it only
|
||
disappears from the buffer after @emph{all} (invisible) characters
|
||
belonging to the ISO timestamp have been removed.
|
||
|
||
@item
|
||
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.
|
||
@end itemize
|
||
|
||
@node Deadlines and Scheduling
|
||
@section 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.
|
||
|
||
@table @asis
|
||
@item @samp{DEADLINE}
|
||
@cindex @samp{DEADLINE}
|
||
Meaning: the task (most likely a TODO item, though not
|
||
necessarily) is supposed to be finished on that date.
|
||
|
||
@vindex org-deadline-warning-days
|
||
On the deadline date, the task is listed in the agenda. In
|
||
addition, the agenda for @emph{today} carries a warning about the
|
||
approaching or missed deadline, starting
|
||
@code{org-deadline-warning-days} before the due date, and continuing
|
||
until the entry is marked DONE. An example:
|
||
|
||
@example
|
||
*** TODO write article about the Earth for the Guide
|
||
DEADLINE: <2004-02-29 Sun>
|
||
The editor in charge is [[bbdb:Ford Prefect]]
|
||
@end example
|
||
|
||
@vindex org-agenda-skip-deadline-prewarning-if-scheduled
|
||
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 @samp{DEADLINE: <2004-02-29 Sun -5d>}.
|
||
This warning is deactivated if the task gets scheduled and you
|
||
set @code{org-agenda-skip-deadline-prewarning-if-scheduled} to @code{t}.
|
||
|
||
@item @samp{SCHEDULED}
|
||
@cindex @samp{SCHEDULED}
|
||
Meaning: you are planning to start working on that task on the
|
||
given date.
|
||
|
||
@vindex org-agenda-skip-scheduled-if-done
|
||
The headline is listed under the given date@footnote{It will still be listed on that date after it has been marked
|
||
DONE. If you do not like this, set the variable
|
||
@code{org-agenda-skip-scheduled-if-done}.}. In addition,
|
||
a reminder that the scheduled date has passed is present in the
|
||
compilation for @emph{today}, until the entry is marked DONE, i.e.,
|
||
the task is automatically forwarded until completed.
|
||
|
||
@example
|
||
*** TODO Call Trillian for a date on New Years Eve.
|
||
SCHEDULED: <2004-12-25 Sat>
|
||
@end example
|
||
|
||
@vindex org-scheduled-delay-days
|
||
@vindex org-agenda-skip-scheduled-delay-if-deadline
|
||
If you want to @emph{delay} the display of this task in the agenda,
|
||
use @samp{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 @samp{--2d} instead. See
|
||
@code{org-scheduled-delay-days} and
|
||
@code{org-agenda-skip-scheduled-delay-if-deadline} for details on how
|
||
to control this globally or per agenda.
|
||
|
||
@noindent
|
||
@strong{Important:} Scheduling an item in Org mode should @emph{not} be
|
||
understood in the same way that we understand @emph{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,
|
||
@emph{scheduling} means setting a date when you want to start working
|
||
on an action item.
|
||
@end table
|
||
|
||
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 @emph{nearest instance} of the
|
||
repeater. However, the use of diary S-exp entries like
|
||
|
||
@example
|
||
<%%(org-float t 42)>
|
||
@end example
|
||
|
||
@noindent
|
||
in scheduling and deadline timestamps is limited. Org mode does not
|
||
know enough about the internals of each S-exp function to issue early
|
||
and late warnings. However, it shows the item on each day where the
|
||
S-exp entry matches.
|
||
|
||
@menu
|
||
* Inserting deadline/schedule:: Planning items.
|
||
* Repeated tasks:: Items that show up again and again.
|
||
@end menu
|
||
|
||
@node Inserting deadline/schedule
|
||
@subsection Inserting deadlines or schedules
|
||
|
||
The following commands allow you to quickly insert a deadline or to
|
||
schedule an item:@footnote{The @samp{SCHEDULED} and @samp{DEADLINE} dates are inserted on the line
|
||
right below the headline. Do not put any text between this line and
|
||
the headline.}
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-d} (@code{org-deadline})
|
||
@kindex C-c C-d
|
||
@findex org-deadline
|
||
@vindex org-log-redeadline
|
||
Insert @samp{DEADLINE} keyword along with a stamp. The insertion
|
||
happens in the line directly following the headline. Remove any
|
||
@samp{CLOSED} timestamp . When called with a prefix argument, also
|
||
remove any existing deadline from the entry. Depending on the
|
||
variable @code{org-log-redeadline}, take a note when changing an
|
||
existing deadline@footnote{Note the corresponding @samp{STARTUP} options @samp{logredeadline},
|
||
@samp{lognoteredeadline}, and @samp{nologredeadline}.}.
|
||
|
||
@item @kbd{C-c C-s} (@code{org-schedule})
|
||
@kindex C-c C-s
|
||
@findex org-schedule
|
||
@vindex org-log-reschedule
|
||
Insert @samp{SCHEDULED} keyword along with a stamp. The insertion
|
||
happens in the line directly following the headline. Remove any
|
||
@samp{CLOSED} timestamp. When called with a prefix argument, also
|
||
remove the scheduling date from the entry. Depending on the
|
||
variable @code{org-log-reschedule}, take a note when changing an
|
||
existing scheduling time@footnote{Note the corresponding @samp{STARTUP} options @samp{logreschedule},
|
||
@samp{lognotereschedule}, and @samp{nologreschedule}.}.
|
||
|
||
@item @kbd{C-c C-x C-k} (@code{org-mark-entry-for-agenda-action})
|
||
@kindex C-c C-x C-k
|
||
@kindex k a
|
||
@kindex k s
|
||
@findex org-mark-entry-for-agenda-action
|
||
Mark the current entry for agenda action. After you have marked
|
||
the entry like this, you can open the agenda or the calendar to
|
||
find an appropriate date. With the cursor on the selected date,
|
||
press @kbd{k s} or @kbd{k d} to schedule the marked
|
||
item.
|
||
|
||
@item @kbd{C-c / d} (@code{org-check-deadlines})
|
||
@kindex C-c / d
|
||
@findex org-check-deadlines
|
||
@cindex sparse tree, for deadlines
|
||
@vindex org-deadline-warning-days
|
||
Create a sparse tree with all deadlines that are either past-due,
|
||
or which will become due within @code{org-deadline-warning-days}.
|
||
With @kbd{C-u} prefix, show all deadlines in the file. With
|
||
a numeric prefix, check that many days. For example, @kbd{C-1 C-c / d} shows all deadlines due tomorrow.
|
||
|
||
@item @kbd{C-c / b}, @code{org-check-before-date}
|
||
@kindex C-c / b
|
||
@findex org-check-before-date
|
||
Sparse tree for deadlines and scheduled items before a given
|
||
date.
|
||
|
||
@item @kbd{C-c / a}, @code{org-check-after-date}
|
||
@kindex C-c / a
|
||
@findex org-check-after-date
|
||
Sparse tree for deadlines and scheduled items after a given date.
|
||
@end table
|
||
|
||
Note that @code{org-schedule} and @code{org-deadline} supports setting the date
|
||
by indicating a relative time e.g., @samp{+1d} sets the date to the next
|
||
day after today, and @samp{--1w} sets the date to the previous week before
|
||
any current timestamp.
|
||
|
||
@node Repeated tasks
|
||
@subsection Repeated tasks
|
||
|
||
@cindex tasks, repeated
|
||
@cindex 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 @samp{DEADLINE},
|
||
@samp{SCHEDULED}, or plain timestamp. In the following example:
|
||
|
||
@example
|
||
** TODO Pay the rent
|
||
DEADLINE: <2005-10-01 Sat +1m>
|
||
@end example
|
||
|
||
noindent
|
||
the @samp{+1m} is a repeater; the intended interpretation is that the task
|
||
has a deadline on @samp{<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 @code{y/w/m/d/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: @samp{DEADLINE:
|
||
<2005-10-01 Sat +1m -3d>}.
|
||
|
||
@vindex org-todo-repeat-to-state
|
||
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
|
||
completed once you have done so. When you mark a @samp{DEADLINE} or
|
||
a @samp{SCHEDULED} with the TODO keyword @samp{DONE}, it no longer produces
|
||
entries in the agenda. The problem with this is, however, is that
|
||
then also the @emph{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 DONE, using @kbd{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@footnote{In fact, the target state is taken from, in this sequence, the
|
||
@samp{REPEAT_TO_STATE} property, the variable @code{org-todo-repeat-to-state} if
|
||
it is a string, the previous TODO state if @code{org-todo-repeat-to-state}
|
||
is @code{t}, or the first state of the TODO state sequence.}. In the example
|
||
above, setting the state to DONE would actually switch the date like
|
||
this:
|
||
|
||
@example
|
||
** TODO Pay the rent
|
||
DEADLINE: <2005-11-01 Tue +1m>
|
||
@end example
|
||
|
||
To mark a task with a repeater as DONE, use @kbd{C-- 1 C-c C-t},
|
||
i.e., @code{org-todo} with a numeric prefix argument of @samp{-1}.
|
||
|
||
@vindex org-log-repeat
|
||
A timestamp@footnote{You can change this using the option @code{org-log-repeat}, or the
|
||
@samp{STARTUP} options @samp{logrepeat}, @samp{lognoterepeat}, and @samp{nologrepeat}.
|
||
With @samp{lognoterepeat}, you will also be prompted for a note.} 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 @samp{+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
|
||
@emph{after} the last time you did it. For these tasks, Org mode has
|
||
special repeaters @samp{++} and @samp{.+}. For example:
|
||
|
||
@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 will shift the date to one month after today.
|
||
@end example
|
||
|
||
@vindex org-agenda-skip-scheduled-if-deadline-is-shown
|
||
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 @code{org-agenda-skip-scheduled-if-deadline-is-shown} to
|
||
@code{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
|
||
@kbd{C-c C-x c} was created for this purpose; it is described in
|
||
@ref{Structure Editing}.
|
||
|
||
@node Clocking Work Time
|
||
@section Clocking Work Time
|
||
|
||
@cindex clocking time
|
||
@cindex time clocking
|
||
|
||
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@footnote{Clocking only works if all headings are indented with less
|
||
than 30 stars. This is a hard-coded limitation of @code{lmax} in
|
||
@code{org-clock-sum}.} of a project. And it remembers a history or tasks
|
||
recently clocked, to that you can jump quickly between a number of
|
||
tasks absorbing your time.
|
||
|
||
To save the clock history across Emacs sessions, use:
|
||
|
||
@lisp
|
||
(setq org-clock-persist 'history)
|
||
(org-clock-persistence-insinuate)
|
||
@end lisp
|
||
|
||
@vindex org-clock-persist
|
||
When you clock into a new task after resuming Emacs, the incomplete
|
||
clock@footnote{To resume the clock under the assumption that you have worked
|
||
on this task while outside Emacs, use @code{(setq org-clock-persist t)}.} is retrieved (see @ref{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.
|
||
@end menu
|
||
|
||
@node Clocking commands
|
||
@subsection Clocking commands
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-x C-i} (@code{org-clock-in})
|
||
@kindex C-c C-x C-i
|
||
@findex org-clock-in
|
||
@vindex org-clock-into-drawer
|
||
@vindex org-clock-continuously
|
||
@cindex @samp{LOG_INTO_DRAWER}, property
|
||
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 @samp{LOGBOOK} drawer (see also the variable
|
||
@code{org-clock-into-drawer}). You can also overrule the setting of
|
||
this variable for a subtree by setting a @samp{CLOCK_INTO_DRAWER} or
|
||
@samp{LOG_INTO_DRAWER} property. When called with a @kbd{C-u}
|
||
prefix argument, select the task from a list of recently clocked
|
||
tasks. With two @kbd{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 @kbd{d} when selecting
|
||
a clocking task. With three @kbd{C-u C-u C-u} prefixes,
|
||
force continuous clocking by starting the clock when the last
|
||
clock stopped.
|
||
|
||
@cindex @samp{CLOCK_MODELINE_TOTAL}, property
|
||
@cindex @samp{LAST_REPEAT}, property
|
||
@vindex org-clock-mode-line-total
|
||
@vindex org-clock-in-prepare-hook
|
||
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 @ref{Effort Estimates}), the mode line displays the current clocking time
|
||
against it@footnote{To add an effort estimate ``on the fly'', hook a function doing
|
||
this to @code{org-clock-in-prepare-hook}.}. If the task is a repeating one (see @ref{Repeated tasks}), show only the time since the last reset of the
|
||
task@footnote{The last reset of the task is recorded by the @samp{LAST_REPEAT}
|
||
property.}. You can exercise more control over show time with
|
||
the @samp{CLOCK_MODELINE_TOTAL} property. It may have the values
|
||
@samp{current} to show only the current clocking instance, @samp{today} to
|
||
show all time clocked on this tasks today---see also the
|
||
variable @code{org-extend-today-until}, @code{all} to include all time, or
|
||
@code{auto} which is the default@footnote{See also the variable @code{org-clock-mode-line-total}.}. Clicking with
|
||
@kbd{mouse-1} onto the mode line entry pops up a menu with
|
||
clocking options.
|
||
|
||
@item @kbd{C-c C-x C-o} (@code{org-clock-out})
|
||
@kindex C-c C-x C-o
|
||
@findex org-clock-out
|
||
@vindex org-log-note-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 @samp{=>HH:MM}. See the variable @code{org-log-note-clock-out}
|
||
for the possibility to record an additional note together with
|
||
the clock-out timestamp@footnote{The corresponding in-buffer setting is: @samp{#+STARTUP:
|
||
lognoteclock-out}.}.
|
||
|
||
@item @kbd{C-c C-x C-x} (@code{org-clock-in-last})
|
||
@kindex C-c C-x C-x
|
||
@findex org-clock-in-last
|
||
@vindex org-clock-continuously
|
||
Re-clock the last clocked task. With one @kbd{C-u} prefix
|
||
argument, select the task from the clock history. With two
|
||
@kbd{C-u} prefixes, force continuous clocking by starting
|
||
the clock when the last clock stopped.
|
||
|
||
@item @kbd{C-c C-x C-e} (@code{org-clock-modify-effort-estimate})
|
||
@kindex C-c C-x C-e
|
||
@findex org-clock-modify-effort-estimate
|
||
Update the effort estimate for the current clock task.
|
||
|
||
@item @kbd{C-c C-c} or @kbd{C-c C-y} (@code{org-evaluate-time-range})
|
||
@kindex C-c C-c
|
||
@kindex C-c C-y
|
||
@findex 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 @kbd{S-<cursor>} keys, the update is
|
||
automatic.
|
||
|
||
@item @kbd{C-S-@key{UP}} (@code{org-clock-timestamps-up})
|
||
@itemx @kbd{C-S-@key{DOWN}} (@code{org-clock-timestamps-down})
|
||
@kindex C-S-UP
|
||
@findex org-clock-timestamps-up
|
||
@kindex C-S-DOWN
|
||
@findex org-clock-timestamps-down
|
||
On CLOCK log lines, increase/decrease both timestamps so that the
|
||
clock duration keeps the same value.
|
||
|
||
@item @kbd{S-M-@key{UP}} (@code{org-timestamp-up})
|
||
@itemx @kbd{S-M-@key{DOWN}} (@code{org-timestamp-down})
|
||
@kindex S-M-UP
|
||
@findex org-clock-timestamp-up
|
||
@kindex S-M-DOWN
|
||
@findex org-clock-timestamp-down
|
||
On @samp{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 @kbd{S-M-@key{UP}} to
|
||
increase a clocked-out timestamp by five minutes, then the
|
||
clocked-in timestamp of the next clock is increased by five
|
||
minutes.
|
||
|
||
@item @kbd{C-c C-t} (@code{org-todo})
|
||
@kindex C-c C-t
|
||
@findex org-todo
|
||
Changing the TODO state of an item to DONE automatically stops
|
||
the clock if it is running in this same item.
|
||
|
||
@item @kbd{C-c C-x C-q} (@code{org-clock-cancel})
|
||
@kindex C-c C-x C-q
|
||
@findex 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.
|
||
|
||
@item @kbd{C-c C-x C-j} (@code{org-clock-goto})
|
||
@kindex C-c C-x C-j
|
||
@findex or-clock-goto
|
||
Jump to the headline of the currently clocked in task. With
|
||
a @kbd{C-u} prefix argument, select the target task from
|
||
a list of recently clocked tasks.
|
||
|
||
@item @kbd{C-c C-x C-d} (@code{org-clock-display})
|
||
@kindex C-c C-x C-d
|
||
@findex org-clock-display
|
||
@vindex org-remove-highlights-with-change
|
||
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 @code{org-remove-highlights-with-change}) or press @kbd{C-c C-c}.
|
||
@end table
|
||
|
||
The @kbd{l} key may be used in the agenda (see @ref{Weekly/daily agenda}) to show which tasks have been worked on or closed during
|
||
a day.
|
||
|
||
@strong{Important:} note that both @code{org-clock-out} and @code{org-clock-in-last}
|
||
can have a global keybinding and do not modify the window disposition.
|
||
|
||
@node The clock table
|
||
@subsection The clock table
|
||
|
||
@cindex clocktable, dynamic block
|
||
@cindex report, of clocked time
|
||
|
||
Org mode can produce quite complex reports based on the time clocking
|
||
information. Such a report is called a @emph{clock table}, because it is
|
||
formatted as one or several Org tables.
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-x C-r} (@code{org-clock-report})
|
||
@kindex C-c C-x C-r
|
||
@findex org-clock-report
|
||
Insert a dynamic block (see @ref{Dynamic Blocks}) containing a clock
|
||
report as an Org mode table into the current file. When the
|
||
cursor is at an existing clock table, just update it. When
|
||
called with a prefix argument, jump to the first clock report in
|
||
the current document and update it. The clock table includes
|
||
archived trees.
|
||
|
||
@item @kbd{C-c C-c} or @kbd{C-c C-x C-u} (@code{org-dblock-update})
|
||
@kindex C-c C-c
|
||
@kindex C-c C-x C-u
|
||
@findex org-dblock-update
|
||
Update dynamic block at point. The cursor needs to be in the
|
||
@samp{BEGIN} line of the dynamic block.
|
||
|
||
@item @kbd{C-u C-c C-x C-u}
|
||
@kindex C-u C-c C-x C-u
|
||
Update all dynamic blocks (see @ref{Dynamic Blocks}). This is useful
|
||
if you have several clock table blocks in a buffer.
|
||
|
||
@item @kbd{S-@key{LEFT}}
|
||
@itemx @kbd{S-@key{RIGHT}} (@code{org-clocktable-try-shift})
|
||
@kindex S-LEFT
|
||
@kindex S-RIGHT
|
||
@findex org-clocktable-try-shift
|
||
Shift the current @samp{:block} interval and update the table. The
|
||
cursor needs to be in the @samp{#+BEGIN: clocktable} line for this
|
||
command. If @samp{:block} is @samp{today}, it is shifted to @samp{today-1},
|
||
etc.
|
||
@end table
|
||
|
||
Here is an example of the frame for a clock table as it is inserted
|
||
into the buffer with the @kbd{C-c C-x C-r} command:
|
||
|
||
@cindex @samp{BEGIN clocktable}
|
||
@example
|
||
#+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file
|
||
#+END: clocktable
|
||
@end example
|
||
|
||
@noindent
|
||
@vindex org-clocktable-defaults
|
||
The @samp{#+BEGIN} line and specify a number of options to define the
|
||
scope, structure, and formatting of the report. Defaults for all
|
||
these options can be configured in the variable
|
||
@code{org-clocktable-defaults}.
|
||
|
||
@noindent
|
||
First there are options that determine which clock entries are to
|
||
be selected:
|
||
|
||
@table @asis
|
||
@item :maxlevel
|
||
Maximum level depth to which times are listed in the table.
|
||
Clocks at deeper levels are summed into the upper level.
|
||
|
||
@item :scope
|
||
The scope to consider. This can be any of the following:
|
||
|
||
@multitable {aaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
|
||
@item @code{nil}
|
||
@tab the current buffer or narrowed region
|
||
@item @code{file}
|
||
@tab the full current buffer
|
||
@item @code{subtree}
|
||
@tab the subtree where the clocktable is located
|
||
@item @code{treeN}
|
||
@tab the surrounding level N tree, for example @samp{tree3}
|
||
@item @code{tree}
|
||
@tab the surrounding level 1 tree
|
||
@item @code{agenda}
|
||
@tab all agenda files
|
||
@item @samp{("file" ...)}
|
||
@tab scan these files
|
||
@item @samp{FUNCTION}
|
||
@tab scan files returned by calling FUNCTION with no argument
|
||
@item @code{file-with-archives}
|
||
@tab current file and its archives
|
||
@item @code{agenda-with-archives}
|
||
@tab all agenda files, including archives
|
||
@end multitable
|
||
|
||
@item :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:
|
||
|
||
@multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaa}
|
||
@item @samp{2007-12-31}
|
||
@tab New year eve 2007
|
||
@item @samp{2007-12}
|
||
@tab December 2007
|
||
@item @samp{2007-W50}
|
||
@tab ISO-week 50 in 2007
|
||
@item @samp{2007-Q2}
|
||
@tab 2nd quarter in 2007
|
||
@item @samp{2007}
|
||
@tab the year 2007
|
||
@item @code{today}, @code{yesterday}, @code{today-N}
|
||
@tab a relative day
|
||
@item @code{thisweek}, @code{lastweek}, @code{thisweek-N}
|
||
@tab a relative week
|
||
@item @code{thismonth}, @code{lastmonth}, @code{thismonth-N}
|
||
@tab a relative month
|
||
@item @code{thisyear}, @code{lastyear}, @code{thisyear-N}
|
||
@tab a relative year
|
||
@item @code{untilnow}
|
||
@tab all clocked time ever
|
||
@end multitable
|
||
|
||
@vindex org-clock-display-default-range
|
||
When this option is not set, Org falls back to the value in
|
||
@code{org-clock-display-default-range}, which defaults to the current
|
||
year.
|
||
|
||
Use @kbd{S-@key{LEFT}} or @kbd{S-@key{RIGHT}} to shift the time
|
||
interval.
|
||
|
||
@item :tstart
|
||
A time string specifying when to start considering times.
|
||
Relative times like @samp{"<-2w>"} can also be used. See @ref{Matching tags and properties} for relative time syntax.
|
||
|
||
@item :tend
|
||
A time string specifying when to stop considering times.
|
||
Relative times like @samp{"<now>"} can also be used. See @ref{Matching tags and properties} for relative time syntax.
|
||
|
||
@item wstart
|
||
The starting day of the week. The default is 1 for Monday.
|
||
|
||
@item mstart
|
||
The starting day of the month. The default is 1 for the first.
|
||
|
||
@item :step
|
||
Set to @code{week} or @code{day} to split the table into chunks. To use
|
||
this, @code{:block} or @code{:tstart}, @code{:tend} are needed.
|
||
|
||
@item :stepskip0
|
||
Do not show steps that have zero time.
|
||
|
||
@item :fileskip0
|
||
Do not show table sections from files which did not contribute.
|
||
|
||
@item :tags
|
||
A tags match to select entries that should contribute. See
|
||
@ref{Matching tags and properties} for the match syntax.
|
||
@end table
|
||
|
||
@findex org-clocktable-write-default
|
||
Then there are options that determine the formatting of the table.
|
||
There options are interpreted by the function
|
||
@code{org-clocktable-write-default}, but you can specify your own function
|
||
using the @samp{:formatter} parameter.
|
||
|
||
@table @asis
|
||
@item :emphasize
|
||
When @code{t}, emphasize level one and level two items.
|
||
|
||
@item :lang
|
||
Language@footnote{Language terms can be set through the variable
|
||
@code{org-clock-clocktable-language-setup}.} to use for descriptive cells like ``Task''.
|
||
|
||
@item :link
|
||
Link the item headlines in the table to their origins.
|
||
|
||
@item :narrow
|
||
An integer to limit the width of the headline column in the Org
|
||
table. If you write it like @samp{50!}, then the headline is also
|
||
shortened in export.
|
||
|
||
@item :indent
|
||
Indent each headline field according to its level.
|
||
|
||
@item :tcolumns
|
||
Number of columns to be used for times. If this is smaller than
|
||
@samp{:maxlevel}, lower levels are lumped into one column.
|
||
|
||
@item :level
|
||
Should a level number column be included?
|
||
|
||
@item :sort
|
||
A cons cell containing the column to sort and a sorting type.
|
||
E.g., @samp{:sort (1 . ?a)} sorts the first column alphabetically.
|
||
|
||
@item :compact
|
||
Abbreviation for @samp{:level nil :indent t :narrow 40! :tcolumns 1}.
|
||
All are overwritten except if there is an explicit @samp{:narrow}.
|
||
|
||
@item :timestamp
|
||
A timestamp for the entry, when available. Look for SCHEDULED,
|
||
DEADLINE, TIMESTAMP and TIMESTAMP_IA special properties (see
|
||
@ref{Special Properties}), in this order.
|
||
|
||
@item :properties
|
||
List of properties shown in the table. Each property gets its
|
||
own column.
|
||
|
||
@item :inherit-props
|
||
When this flag is non-@code{nil}, the values for @samp{:properties} are
|
||
inherited.
|
||
|
||
@item :formula
|
||
Content of a @samp{TBLFM} keyword to be added and evaluated. As
|
||
a special case, @samp{: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.
|
||
|
||
@item :formatter
|
||
A function to format clock data and insert it into the buffer.
|
||
@end table
|
||
|
||
To get a clock summary of the current level 1 tree, for the current
|
||
day, you could write:
|
||
|
||
@example
|
||
#+BEGIN: clocktable :maxlevel 2 :block today :scope tree1 :link t
|
||
#+END: clocktable
|
||
@end example
|
||
|
||
@noindent
|
||
To use a specific time range you could write@footnote{Note that all parameters must be specified in a single
|
||
line---the line is broken here only to fit it into the manual.}
|
||
|
||
@example
|
||
#+BEGIN: clocktable :tstart "<2006-08-10 Thu 10:00>"
|
||
:tend "<2006-08-10 Thu 12:00>"
|
||
#+END: clocktable
|
||
@end example
|
||
|
||
A range starting a week ago and ending right now could be written as
|
||
|
||
@example
|
||
#+BEGIN: clocktable :tstart "<-1w>" :tend "<now>"
|
||
#+END: clocktable
|
||
@end example
|
||
|
||
A summary of the current subtree with % times would be:
|
||
|
||
@example
|
||
#+BEGIN: clocktable :scope subtree :link t :formula %
|
||
#+END: clocktable
|
||
@end example
|
||
|
||
A horizontally compact representation of everything clocked during
|
||
last week would be:
|
||
|
||
@example
|
||
#+BEGIN: clocktable :scope agenda :block lastweek :compact t
|
||
#+END: clocktable
|
||
@end example
|
||
|
||
@node Resolving idle time
|
||
@subsection Resolving idle time and continuous clocking
|
||
|
||
|
||
|
||
@anchor{Resolving idle time (1)}
|
||
@subsubheading Resolving idle time
|
||
|
||
@cindex resolve idle time
|
||
@cindex idle, resolve, dangling
|
||
|
||
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.
|
||
|
||
@vindex org-clock-idle-time
|
||
@vindex org-clock-x11idle-program-name
|
||
By customizing the variable @code{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@footnote{On computers using macOS, idleness is based on actual user
|
||
idleness, not just Emacs' idle time. For X11, you can install
|
||
a utility program @samp{x11idle.c}, available in the @samp{contrib/scripts/}
|
||
directory of the Org Git distribution, or install the xprintidle
|
||
package and set it to the variable @code{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.}, 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:
|
||
|
||
@table @asis
|
||
@item @kbd{k}
|
||
@kindex k
|
||
To keep some or all of the minutes and stay clocked in, press
|
||
@kbd{k}. Org asks how many of the minutes to keep. Press
|
||
@kbd{@key{RET}} to keep them all, effectively changing nothing, or
|
||
enter a number to keep that many minutes.
|
||
|
||
@item @kbd{K}
|
||
@kindex K
|
||
If you use the shift key and press @kbd{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.
|
||
|
||
@item @kbd{s}
|
||
@kindex s
|
||
To keep none of the minutes, use @kbd{s} to subtract all the
|
||
away time from the clock, and then check back in from the moment
|
||
you returned.
|
||
|
||
@item @kbd{S}
|
||
@kindex S
|
||
To keep none of the minutes and just clock out at the start of
|
||
the away time, use the shift key and press @kbd{S}.
|
||
Remember that using shift always leave you clocked out, no matter
|
||
which option you choose.
|
||
|
||
@item @kbd{C}
|
||
@kindex C
|
||
To cancel the clock altogether, use @kbd{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.
|
||
@end table
|
||
|
||
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 @kbd{M-x org-resolve-clocks @key{RET}} (or @kbd{C-c C-x C-z}).
|
||
|
||
@anchor{Continuous clocking}
|
||
@subsubheading Continuous clocking
|
||
|
||
@cindex continuous clocking
|
||
|
||
@vindex org-clock-continuously
|
||
You may want to start clocking from the time when you clocked out the
|
||
previous task. To enable this systematically, set
|
||
@code{org-clock-continuously} to non-@code{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 @code{org-clock-in} and two @kbd{C-u C-u} with
|
||
@code{org-clock-in-last}.
|
||
|
||
@node Effort Estimates
|
||
@section Effort Estimates
|
||
|
||
@cindex effort estimates
|
||
@cindex @samp{EFFORT}, property
|
||
@vindex org-effort-property
|
||
|
||
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
|
||
@samp{EFFORT}. You can set the effort for an entry with the following
|
||
commands:
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-x e} (@code{org-set-effort})
|
||
@kindex C-c C-x e
|
||
@findex 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 @kbd{e}
|
||
key.
|
||
|
||
@item @kbd{C-c C-x C-e} (@code{org-clock-modify-effort-estimate})
|
||
@kindex C-c C-x C-e
|
||
@findex org-clock-modify-effort-estimate
|
||
Modify the effort estimate of the item currently being clocked.
|
||
@end table
|
||
|
||
Clearly the best way to work with effort estimates is through column
|
||
view (see @ref{Column View}). You should start by setting up discrete
|
||
values for effort estimates, and a @samp{COLUMNS} format that displays
|
||
these values together with clock sums---if you want to clock your
|
||
time. For a specific buffer you can use:
|
||
|
||
@example
|
||
#+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
|
||
@end example
|
||
|
||
noindent
|
||
@vindex org-global-properties
|
||
@vindex org-columns-default-format
|
||
or, even better, you can set up these values globally by customizing
|
||
the variables @code{org-global-properties} and
|
||
@code{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 @kbd{S-@key{RIGHT}} and @kbd{S-@key{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.
|
||
|
||
@vindex org-agenda-columns-add-appointments-to-effort-sum
|
||
If you switch to column view in the daily/weekly agenda, the effort
|
||
column summarizes the estimated work effort for each day@footnote{Please note the pitfalls of summing hierarchical data in
|
||
a flat list (@ref{Agenda Column View}).}, 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 @code{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 @kbd{/} key in the agenda (see @ref{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.
|
||
|
||
@node Timers
|
||
@section Taking Notes with a Relative Timer
|
||
|
||
@cindex relative timer
|
||
@cindex countdown 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.
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-x 0} (@code{org-timer-start})
|
||
@kindex C-c C-x 0
|
||
@findex org-timer-start
|
||
Start or reset the relative timer. By default, the timer is set
|
||
to 0. When called with a @kbd{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 @kbd{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.
|
||
|
||
@item @kbd{C-c C-x ;} (@code{org-timer-set-timer})
|
||
@kindex C-c C-x ;
|
||
@findex org-timer-set-timer
|
||
@vindex org-timer-default-timer
|
||
Start a countdown timer. The user is prompted for a duration.
|
||
@code{org-timer-default-timer} sets the default countdown value.
|
||
Giving a numeric prefix argument overrides this default value.
|
||
This command is available as @kbd{;} in agenda buffers.
|
||
@end table
|
||
|
||
Once started, relative and countdown timers are controlled with the
|
||
same commands.
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-x .} (@code{org-timer})
|
||
@kindex C-c C-x .
|
||
@findex org-timer
|
||
Insert a relative time into the buffer. The first time you use
|
||
this, the timer starts. Using a prefix argument restarts it.
|
||
|
||
@item @kbd{C-c C-x -} (@code{org-timer-item})
|
||
@kindex C-c C-x -
|
||
@findex org-timer-item
|
||
Insert a description list item with the current relative time.
|
||
With a prefix argument, first reset the timer to 0.
|
||
|
||
@item @kbd{M-@key{RET}} (@code{org-insert-heading})
|
||
@kindex M-RET
|
||
@findex org-insert-heading
|
||
Once the timer list is started, you can also use
|
||
@kbd{M-@key{RET}} to insert new timer items.
|
||
|
||
@item @kbd{C-c C-x ,} (@code{org-timer-pause-or-continue})
|
||
@kindex C-c C-x ,
|
||
@findex org-timer-pause-or-continue
|
||
Pause the timer, or continue it if it is already paused.
|
||
|
||
@item @kbd{C-c C-x _} (@code{org-timer-stop})
|
||
@kindex C-c C-x _
|
||
@findex 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.
|
||
@end table
|
||
|
||
@node Capture Refile Archive
|
||
@chapter Capture, Refile, Archive
|
||
|
||
@cindex capture
|
||
|
||
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 @emph{capture}. It also can
|
||
store files related to a task (@emph{attachments}) in a special directory.
|
||
Once in the system, tasks and projects need to be moved around.
|
||
Moving completed project trees to an archive file keeps the system
|
||
compact and fast.
|
||
|
||
@menu
|
||
* Capture:: Capturing new stuff.
|
||
* Attachments:: Add files to tasks.
|
||
* RSS Feeds:: Getting input from RSS feeds.
|
||
* Protocols:: External access to Emacs and Org.
|
||
* Refile and Copy:: Moving/copying a tree from one place to another.
|
||
* Archiving:: What to do with finished products.
|
||
@end menu
|
||
|
||
@node Capture
|
||
@section Capture
|
||
|
||
@cindex 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.
|
||
@end menu
|
||
|
||
@node Setting up capture
|
||
@subsection Setting up capture
|
||
|
||
The following customization sets a default target file for notes.
|
||
|
||
@vindex org-default-notes-file
|
||
@lisp
|
||
(setq org-default-notes-file (concat org-directory "/notes.org"))
|
||
@end lisp
|
||
|
||
You may also define a global key for capturing new material (see
|
||
@ref{Activation}).
|
||
|
||
@node Using capture
|
||
@subsection Using capture
|
||
|
||
@table @asis
|
||
@item @kbd{M-x org-capture} (@code{org-capture})
|
||
@findex org-capture
|
||
@cindex date tree
|
||
Display the capture templates menu. If you have templates
|
||
defined (see @ref{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.
|
||
|
||
@item @kbd{C-c C-c} (@code{org-capture-finalize})
|
||
@kindex C-c C-c @r{(Capture buffer)}
|
||
@findex org-capture-finalize
|
||
Once you have finished entering information into the capture
|
||
buffer, @kbd{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.
|
||
|
||
@item @kbd{C-c C-w} (@code{org-capture-refile})
|
||
@kindex C-c C-w @r{(Capture buffer)}
|
||
@findex org-capture-refile
|
||
Finalize the capture process by refiling the note to a different
|
||
place (see @ref{Refile and Copy}). Please realize that this is
|
||
a normal refiling command that will be executed---so the cursor
|
||
position at the moment you run this command is important. If you
|
||
have inserted a tree with a parent and children, first move the
|
||
cursor back to the parent. Any prefix argument given to this
|
||
command is passed on to the @code{org-refile} command.
|
||
|
||
@item @kbd{C-c C-k} (@code{org-capture-kill})
|
||
@kindex C-c C-k @r{(Capture buffer)}
|
||
@findex org-capture-kill
|
||
Abort the capture process and return to the previous state.
|
||
@end table
|
||
|
||
@kindex k c @r{(Agenda)}
|
||
You can also call @code{org-capture} in a special way from the agenda,
|
||
using the @kbd{k c} key combination. With this access, any
|
||
timestamps inserted by the selected capture template defaults to the
|
||
cursor date in the agenda, rather than to the current date.
|
||
|
||
To find the locations of the last stored capture, use @code{org-capture}
|
||
with prefix commands:
|
||
|
||
@table @asis
|
||
@item @kbd{C-u M-x org-capture}
|
||
Visit the target location of a capture template. You get to
|
||
select the template in the usual way.
|
||
|
||
@item @kbd{C-u C-u M-x org-capture}
|
||
Visit the last stored capture item in its buffer.
|
||
@end table
|
||
|
||
@vindex org-capture-bookmark
|
||
@vindex org-capture-last-stored
|
||
You can also jump to the bookmark @code{org-capture-last-stored}, which is
|
||
automatically created unless you set @code{org-capture-bookmark} to @code{nil}.
|
||
|
||
To insert the capture at point in an Org buffer, call @code{org-capture}
|
||
with a @code{C-0} prefix argument.
|
||
|
||
@node Capture templates
|
||
@subsection Capture templates
|
||
|
||
@cindex templates, for Capture
|
||
|
||
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.
|
||
|
||
@table @asis
|
||
@item @kbd{C}
|
||
@kindex C @r{(Capture menu}
|
||
@vindex org-capture-templates
|
||
Customize the variable @code{org-capture-templates}.
|
||
@end table
|
||
|
||
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 @samp{Tasks} in your file @samp{~/org/gtd.org}. Also, a date tree in
|
||
the file @samp{journal.org} should capture journal entries. A possible
|
||
configuration would look like:
|
||
|
||
@lisp
|
||
(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")))
|
||
@end lisp
|
||
|
||
@noindent
|
||
If you then press @kbd{t} from the capture menu, Org will prepare
|
||
the template for you like this:
|
||
|
||
@example
|
||
* TODO
|
||
[[file:LINK TO WHERE YOU INITIATED CAPTURE]]
|
||
@end example
|
||
|
||
@noindent
|
||
During expansion of the template, @code{%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 @kbd{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:
|
||
|
||
@lisp
|
||
(define-key global-map "\C-cx"
|
||
(lambda () (interactive) (org-capture nil "x")))
|
||
@end lisp
|
||
|
||
@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.
|
||
@end menu
|
||
|
||
@node Template elements
|
||
@subsubsection Template elements
|
||
|
||
Now lets look at the elements of a template definition. Each entry in
|
||
@code{org-capture-templates} is a list with the following items:
|
||
|
||
@table @asis
|
||
@item keys
|
||
The keys that selects the template, as a string, characters only,
|
||
for example @samp{"a"}, for a template to be selected with a single
|
||
key, or @samp{"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:
|
||
|
||
@lisp
|
||
("b" "Templates for marking stuff to buy")
|
||
@end lisp
|
||
|
||
@noindent
|
||
If you do not define a template for the @kbd{C} key, this
|
||
key opens the Customize buffer for this complex variable.
|
||
|
||
@item description
|
||
A short string describing the template, shown during selection.
|
||
|
||
@item type
|
||
The type of entry, a symbol. Valid values are:
|
||
|
||
@table @asis
|
||
@item @code{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 @code{item}
|
||
A plain list item, placed in the first plain list at the
|
||
target location. Again the target file should be an Org
|
||
file.
|
||
|
||
@item @code{checkitem}
|
||
A checkbox item. This only differs from the plain list item
|
||
by the default template.
|
||
|
||
@item @code{table-line}
|
||
A new line in the first table at the target location. Where
|
||
exactly the line will be inserted depends on the properties
|
||
@code{:prepend} and @code{:table-line-pos} (see below).
|
||
|
||
@item @code{plain}
|
||
Text to be inserted as it is.
|
||
@end table
|
||
|
||
@item target
|
||
@vindex org-default-notes-file
|
||
@vindex org-directory
|
||
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 @code{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 @code{org-directory}.
|
||
|
||
Valid values are:
|
||
|
||
@table @asis
|
||
@item @samp{(file "path/to/file")}
|
||
Text will be placed at the beginning or end of that file.
|
||
|
||
@item @samp{(id "id of existing org entry")}
|
||
Filing as child of this entry, or in the body of the entry.
|
||
|
||
@item @samp{(file+headline "filename" "node headline")}
|
||
Fast configuration if the target heading is unique in the file.
|
||
|
||
@item @samp{(file+olp "filename" "Level 1 heading" "Level 2" ...)}
|
||
For non-unique headings, the full path is safer.
|
||
|
||
@item @samp{(file+regexp "filename" "regexp to find location")}
|
||
Use a regular expression to position the cursor.
|
||
|
||
@item @samp{(file+olp+datetree "filename" [ "Level 1 heading" ...])}
|
||
This target@footnote{Org used to offer four different targets for date/week tree
|
||
capture. Now, Org automatically translates these to use
|
||
@code{file+olp+datetree}, applying the @code{:time-prompt} and @code{:tree-type}
|
||
properties. Please rewrite your date/week-tree targets using
|
||
@code{file+olp+datetree} since the older targets are now deprecated.} creates a heading in a date tree@footnote{A date tree is an outline structure with years on the highest
|
||
level, months or ISO weeks as sublevels and then dates on the lowest
|
||
level. Tags are allowed in the tree structure.} 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 @code{:time-prompt} and @code{:tree-type}
|
||
properties below for additional options.
|
||
|
||
@item @code{(file+function "filename" function-finding-location)}
|
||
A function to find the right location in the file.
|
||
|
||
@item @code{(clock)}
|
||
File to the entry that is currently being clocked.
|
||
|
||
@item @code{(function function-finding-location)}
|
||
Most general way: write your own function which both visits the
|
||
file and moves point to the right location.
|
||
@end table
|
||
|
||
@item 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. The string
|
||
with escapes may be loaded from a template file, using the
|
||
special syntax @samp{(file "template filename")}. See below for more
|
||
details.
|
||
|
||
@item properties
|
||
The rest of the entry is a property list of additional options.
|
||
Recognized properties are:
|
||
|
||
@table @asis
|
||
@item @code{:prepend}
|
||
Normally new captured information will be appended at the
|
||
target location (last child, last table line, last list item,
|
||
@dots{}). Setting this property changes that.
|
||
|
||
@item @code{: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.
|
||
|
||
@item @code{: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.
|
||
|
||
@item @code{:clock-in}
|
||
Start the clock in this item.
|
||
|
||
@item @code{:clock-keep}
|
||
Keep the clock running when filing the captured entry.
|
||
|
||
@item @code{:clock-resume}
|
||
If starting the capture interrupted a clock, restart that clock
|
||
when finished with the capture. Note that @code{:clock-keep} has
|
||
precedence over @code{:clock-resume}. When setting both to
|
||
non-@code{nil}, the current clock will run and the previous one will
|
||
not be resumed.
|
||
|
||
@item @code{: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 @code{org-capture} with
|
||
a @kbd{C-1} prefix argument.
|
||
|
||
@item @code{:tree-type}
|
||
When @code{week}, make a week tree instead of the month tree, i.e.,
|
||
place the headings for each day under a heading with the
|
||
current ISO week.
|
||
|
||
@item @code{: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.
|
||
|
||
@item @code{:table-line-pos}
|
||
Specification of the location in the table where the new line
|
||
should be inserted. It should be a string like @samp{II-3} meaning
|
||
that the new line should become the third line before the
|
||
second horizontal separator line.
|
||
|
||
@item @code{:kill-buffer}
|
||
If the target file was not yet visited when capture was invoked, kill
|
||
the buffer again after capture is completed.
|
||
@end table
|
||
@end table
|
||
|
||
@node Template expansion
|
||
@subsubsection Template expansion
|
||
|
||
In the template itself, special ``%-escapes''@footnote{If you need one of these sequences literally, escape the @samp{%}
|
||
with a backslash.} allow dynamic
|
||
insertion of content. The templates are expanded in the order given
|
||
here:
|
||
|
||
@table @asis
|
||
@item @code{%[FILE]}
|
||
Insert the contents of the file given by @var{FILE}.
|
||
|
||
@item @code{%(SEXP)}
|
||
Evaluate Elisp SEXP and replace with the result. The
|
||
@var{SEXP} must return a string.
|
||
|
||
@item @code{%<FORMAT>}
|
||
The result of format-time-string on the @var{FORMAT}
|
||
specification.
|
||
|
||
@item @code{%t}
|
||
Timestamp, date only.
|
||
|
||
@item @code{%T}
|
||
Timestamp, with date and time.
|
||
|
||
@item @code{%u}, @code{%U}
|
||
Like @code{%t}, @code{%T} above, but inactive timestamps.
|
||
|
||
@item @code{%i}
|
||
Initial content, the region when capture is called while the
|
||
region is active. The entire text will be indented like @code{%i}
|
||
itself.
|
||
|
||
@item @code{%a}
|
||
Annotation, normally the link created with @code{org-store-link}.
|
||
|
||
@item @code{%A}
|
||
Like @code{%a}, but prompt for the description part.
|
||
|
||
@item @code{%l}
|
||
Like @code{%a}, but only insert the literal link.
|
||
|
||
@item @code{%c}
|
||
Current kill ring head.
|
||
|
||
@item @code{%x}
|
||
Content of the X clipboard.
|
||
|
||
@item @code{%k}
|
||
Title of the currently clocked task.
|
||
|
||
@item @code{%K}
|
||
Link to the currently clocked task.
|
||
|
||
@item @code{%n}
|
||
User name (taken from @code{user-full-name}).
|
||
|
||
@item @code{%f}
|
||
File visited by current buffer when org-capture was called.
|
||
|
||
@item @code{%F}
|
||
Full path of the file or directory visited by current buffer.
|
||
|
||
@item @code{%:keyword}
|
||
Specific information for certain link types, see below.
|
||
|
||
@item @code{%^g}
|
||
Prompt for tags, with completion on tags in target file.
|
||
|
||
@item @code{%^G}
|
||
Prompt for tags, with completion all tags in all agenda files.
|
||
|
||
@item @code{%^t}
|
||
Like @code{%t}, but prompt for date. Similarly @code{%^T}, @code{%^u}, @code{%^U}. You may
|
||
define a prompt like @code{%^@{Birthday@}t}.
|
||
|
||
@item @code{%^C}
|
||
Interactive selection of which kill or clip to use.
|
||
|
||
@item @code{%^L}
|
||
Like @code{%^C}, but insert as link.
|
||
|
||
@item @code{%^@{PROP@}p}
|
||
Prompt the user for a value for property PROP.
|
||
|
||
@item @code{%^@{PROMPT@}}
|
||
Prompt the user for a string and replace this sequence with it.
|
||
You may specify a default value and a completion table with
|
||
@code{%^@{prompt|default|completion2|completion3...@}}. The arrow keys
|
||
access a prompt-specific history.
|
||
|
||
@item @code{%\n}
|
||
Insert the text entered at the Nth @code{%^@{PROMPT@}}, where N is
|
||
a number, starting from 1.
|
||
|
||
@item @code{%?}
|
||
After completing the template, position cursor here.
|
||
@end table
|
||
|
||
@noindent
|
||
@vindex org-store-link-props
|
||
For specific link types, the following keywords are defined@footnote{If you define your own link types (see @ref{Adding Hyperlink Types}), any property you store with @code{org-store-link-props} can be
|
||
accessed in capture templates in a similar way.}:
|
||
|
||
@vindex org-from-is-user-regexp
|
||
@multitable {aaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
|
||
@headitem Link type
|
||
@tab Available keywords
|
||
@item bbdb
|
||
@tab @code{%:name}, @code{%:company}
|
||
@item irc
|
||
@tab @code{%:server}, @code{%:port}, @code{%:nick}
|
||
@item mh, rmail
|
||
@tab @code{%:type}, @code{%:subject}, @code{%:message-id}
|
||
@item
|
||
@tab @code{%:from}, @code{%:fromname}, @code{%:fromaddress}
|
||
@item
|
||
@tab @code{%:to}, @code{%:toname}, @code{%:toaddress}
|
||
@item
|
||
@tab @code{%:date} (message date header field)
|
||
@item
|
||
@tab @code{%:date-timestamp} (date as active timestamp)
|
||
@item
|
||
@tab @code{%:date-timestamp-inactive} (date as inactive timestamp)
|
||
@item
|
||
@tab @code{%:fromto} (either ``to NAME'' or ``from NAME'')@footnote{This is always the other, not the user. See the variable
|
||
@code{org-from-is-user-regexp}.}
|
||
@item gnus
|
||
@tab @code{%:group}, for messages also all email fields
|
||
@item w3, w3m
|
||
@tab @code{%:url}
|
||
@item info
|
||
@tab @code{%:file}, @code{%:node}
|
||
@item calendar
|
||
@tab @code{%:date}
|
||
@item org-protocol
|
||
@tab @code{%:link}, @code{%:description}, @code{%:annotation}
|
||
@end multitable
|
||
|
||
@node Templates in contexts
|
||
@subsubsection Templates in contexts
|
||
|
||
@vindex org-capture-templates-contexts
|
||
To control whether a capture template should be accessible from
|
||
a specific context, you can customize
|
||
@code{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:
|
||
|
||
@lisp
|
||
(setq org-capture-templates-contexts
|
||
'(("p" (in-mode . "message-mode"))))
|
||
@end lisp
|
||
|
||
You can also tell that the command key @kbd{p} should refer to
|
||
another template. In that case, add this command key like this:
|
||
|
||
@lisp
|
||
(setq org-capture-templates-contexts
|
||
'(("p" "q" (in-mode . "message-mode"))))
|
||
@end lisp
|
||
|
||
See the docstring of the variable for more information.
|
||
|
||
@node Attachments
|
||
@section Attachments
|
||
|
||
@cindex attachments
|
||
@vindex org-attach-directory
|
||
|
||
It is often useful to associate reference material with an outline
|
||
node/task. Small chunks of plain text can simply be stored in the
|
||
subtree of a project. Hyperlinks (see @ref{Hyperlinks}) can establish
|
||
associations with files that live elsewhere on your computer or in the
|
||
cloud, like emails or source code files belonging to a project.
|
||
Another method is @emph{attachments}, which are files located in
|
||
a directory belonging to an outline node. Org uses directories named
|
||
by the unique ID of each entry. These directories are located in the
|
||
@code{data} directory which lives in the same directory where your Org file
|
||
lives@footnote{If you move entries or Org files from one directory to
|
||
another, you may want to configure @code{org-attach-directory} to contain
|
||
an absolute path.}. If you initialize this directory with @samp{git init}, Org
|
||
automatically commits changes when it sees them. The attachment
|
||
system has been contributed to Org by John Wiegley.
|
||
|
||
In cases where it seems better to do so, you can attach a directory of
|
||
your choice to an entry. You can also make children inherit the
|
||
attachment directory from a parent, so that an entire subtree uses the
|
||
same attached directory.
|
||
|
||
@noindent
|
||
The following commands deal with attachments:
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-a} (@code{org-attach})
|
||
@kindex C-c C-a
|
||
@findex 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:
|
||
|
||
@table @asis
|
||
@item @kbd{a} (@code{org-attach-attach})
|
||
@kindex C-c C-a a
|
||
@findex org-attach-attach
|
||
@vindex org-attach-method
|
||
Select a file and move it into the task's attachment
|
||
directory. The file is copied, moved, or linked, depending
|
||
on @code{org-attach-method}. Note that hard links are not
|
||
supported on all systems.
|
||
|
||
@item @kbd{c}/@kbd{m}/@kbd{l}
|
||
@kindex C-c C-a c
|
||
@kindex C-c C-a m
|
||
@kindex C-c C-a l
|
||
Attach a file using the copy/move/link method. Note that
|
||
hard links are not supported on all systems.
|
||
|
||
@item @kbd{n} (@code{org-attach-new})
|
||
@kindex C-c C-a n
|
||
@findex org-attach-new
|
||
Create a new attachment as an Emacs buffer.
|
||
|
||
@item @kbd{z} (@code{org-attach-sync})
|
||
@kindex C-c C-a z
|
||
@findex org-attach-sync
|
||
Synchronize the current task with its attachment directory, in case
|
||
you added attachments yourself.
|
||
|
||
@item @kbd{o} (@code{org-attach-open})
|
||
@kindex C-c C-a o
|
||
@findex org-attach-open
|
||
@vindex org-file-apps
|
||
Open current task's attachment. If there is more than one,
|
||
prompt for a file name first. Opening follows the rules set
|
||
by @code{org-file-apps}. For more details, see the information
|
||
on following hyperlinks (see @ref{Handling Links}).
|
||
|
||
@item @kbd{O} (@code{org-attach-open-in-emacs})
|
||
@kindex C-c C-a O
|
||
@findex org-attach-open-in-emacs
|
||
Also open the attachment, but force opening the file in
|
||
Emacs.
|
||
|
||
@item @kbd{f} (@code{org-attach-reveal})
|
||
@kindex C-c C-a f
|
||
@findex org-attach-reveal
|
||
Open the current task's attachment directory.
|
||
|
||
@item @kbd{F} (@code{org-attach-reveal-in-emacs})
|
||
@kindex C-c C-a F
|
||
@findex org-attach-reveal-in-emacs
|
||
Also open the directory, but force using Dired in Emacs.
|
||
|
||
@item @kbd{d} (@code{org-attach-delete-one})
|
||
@kindex C-c C-a d
|
||
Select and delete a single attachment.
|
||
|
||
@item @kbd{D} (@code{org-attach-delete-all})
|
||
@kindex C-c C-a D
|
||
Delete all of a task's attachments. A safer way is to open
|
||
the directory in Dired and delete from there.
|
||
|
||
@item @kbd{s} (@code{org-attach-set-directory})
|
||
@kindex C-c C-a s
|
||
@cindex @samp{ATTACH_DIR}, property
|
||
Set a specific directory as the entry's attachment
|
||
directory. This works by putting the directory path into
|
||
the @samp{ATTACH_DIR} property.
|
||
|
||
@item @kbd{i} (@code{org-attach-set-inherit})
|
||
@kindex C-c C-a i
|
||
@cindex @samp{ATTACH_DIR_INHERIT}, property
|
||
Set the @samp{ATTACH_DIR_INHERIT} property, so that children use
|
||
the same directory for attachments as the parent does.
|
||
@end table
|
||
@end table
|
||
|
||
@cindex attach from Dired
|
||
@findex org-attach-dired-to-subtree
|
||
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,
|
||
@kbd{M-x org-attach-dired-to-subtree} attaches the file to the
|
||
subtree using the attachment method set by variable
|
||
@code{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 @kbd{C-c C-x a} attach files in Dired buffers.
|
||
|
||
@lisp
|
||
(add-hook 'dired-mode-hook
|
||
(lambda ()
|
||
(define-key dired-mode-map
|
||
(kbd "C-c C-x a")
|
||
#'org-attach-dired-to-subtree))))
|
||
@end lisp
|
||
|
||
The following code shows how to bind the previous command with
|
||
a specific attachment method.
|
||
|
||
@lisp
|
||
(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))))))
|
||
@end lisp
|
||
|
||
@node RSS Feeds
|
||
@section RSS Feeds
|
||
|
||
@cindex RSS feeds
|
||
@cindex Atom 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 @code{org-feed-alist}. The docstring of this
|
||
variable has detailed information. With the following
|
||
|
||
@lisp
|
||
(setq org-feed-alist
|
||
'(("Slashdot"
|
||
"http://rss.slashdot.org/Slashdot/slashdot"
|
||
"~/txt/org/feeds.org" "Slashdot Entries")))
|
||
@end lisp
|
||
|
||
@noindent
|
||
new items from the feed provided by @samp{rss.slashdot.org} result in new
|
||
entries in the file @samp{~/org/feeds.org} under the heading @samp{Slashdot
|
||
Entries}, whenever the following command is used:
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-x g} (@code{org-feed-update-all})
|
||
@kindex C-c C-x g
|
||
Collect items from the feeds configured in @code{org-feed-alist} and
|
||
act upon them.
|
||
|
||
@item @kbd{C-c C-x G} (@code{org-feed-goto-inbox})
|
||
@kindex C-c C-x G
|
||
Prompt for a feed name and go to the inbox configured for this feed.
|
||
@end table
|
||
|
||
Under the same headline, Org creates a drawer @samp{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
|
||
@samp{org-feed.el} and the docstring of @code{org-feed-alist}.
|
||
|
||
@node Protocols
|
||
@section Protocols for External Access
|
||
|
||
@cindex protocols, for external access
|
||
|
||
Org protocol is a means 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 @ref{Capture}). You can also create a bookmark that tells
|
||
Emacs to open the local source file of a remote website you are
|
||
browsing.
|
||
|
||
@cindex Org protocol, set-up
|
||
@cindex Installing Org protocol
|
||
In order to use Org protocol from an application, you need to register
|
||
@samp{org-protocol://} as a valid scheme-handler. External calls are
|
||
passed to Emacs through the @samp{emacsclient} command, so you also need to
|
||
ensure an Emacs server is running. More precisely, when the
|
||
application calls
|
||
|
||
@example
|
||
emacsclient org-protocol://PROTOCOL?key1=val1&key2=val2
|
||
@end example
|
||
|
||
@noindent
|
||
Emacs calls the handler associated to @var{PROTOCOL} with
|
||
argument @samp{(:key1 val1 :key2 val2)}.
|
||
|
||
@cindex protocol, new protocol
|
||
@cindex defining new protocols
|
||
Org protocol comes with three predefined protocols, detailed in the
|
||
following sections. Configure @code{org-protocol-protocol-alist} to define
|
||
your own.
|
||
|
||
@menu
|
||
* @code{store-link} protocol:: Store a link, push URL to kill-ring.
|
||
* @code{capture} protocol:: Fill a buffer with external information.
|
||
* @code{open-source} protocol:: Edit published contents.
|
||
@end menu
|
||
|
||
@node @code{store-link} protocol
|
||
@subsection @code{store-link} protocol
|
||
|
||
@cindex store-link protocol
|
||
@cindex protocol, store-link
|
||
|
||
Using @code{store-link} handler, you can copy links, insertable through
|
||
@kbd{M-x org-insert-link} or yanking thereafter. More precisely,
|
||
the command
|
||
|
||
@example
|
||
emacsclient org-protocol://store-link?url=URL&title=TITLE
|
||
@end example
|
||
|
||
@noindent
|
||
stores the following link:
|
||
|
||
@example
|
||
[[URL][TITLE]]
|
||
@end example
|
||
|
||
In addition, @var{URL} is pushed on the kill-ring for yanking.
|
||
You need to encode @var{URL} and @var{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., @samp{Org: store-link} and enter this as @emph{Location}:
|
||
|
||
@example
|
||
javascript:location.href='org-protocol://store-link?url='+
|
||
encodeURIComponent(location.href);
|
||
@end example
|
||
|
||
@node @code{capture} protocol
|
||
@subsection @code{capture} protocol
|
||
|
||
@cindex capture protocol
|
||
@cindex protocol, capture
|
||
|
||
Activating ``capture'' handler pops up a @samp{Capture} buffer and fills the
|
||
capture template associated to the @samp{X} key with them.
|
||
|
||
@example
|
||
emacsclient org-protocol://capture?template=X?url=URL?title=TITLE?body=BODY
|
||
@end example
|
||
|
||
To use this feature, add a bookmark with an arbitrary name, e.g.
|
||
@samp{Org: capture} and enter this as @samp{Location}:
|
||
|
||
@example
|
||
javascript:location.href='org-protocol://capture?template=x'+
|
||
'&url='+encodeURIComponent(window.location.href)+
|
||
'&title='+encodeURIComponent(document.title)+
|
||
'&body='+encodeURIComponent(window.getSelection());
|
||
@end example
|
||
|
||
@vindex org-protocol-default-template-key
|
||
The result depends on the capture template used, which is set in the
|
||
bookmark itself, as in the example above, or in
|
||
@code{org-protocol-default-template-key}.
|
||
|
||
The following template placeholders are available:
|
||
|
||
@example
|
||
%:link The URL
|
||
%:description The webpage title
|
||
%:annotation Equivalent to [[%:link][%:description]]
|
||
%i The selected text
|
||
@end example
|
||
|
||
@node @code{open-source} protocol
|
||
@subsection @code{open-source} protocol
|
||
|
||
@cindex open-source protocol
|
||
@cindex protocol, open-source
|
||
|
||
The @code{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:
|
||
|
||
@example
|
||
javascript:location.href='org-protocol://open-source?&url='+
|
||
encodeURIComponent(location.href)
|
||
@end example
|
||
|
||
@vindex org-protocol-project-alist
|
||
The variable @code{org-protocol-project-alist} maps URLs to local file
|
||
names, by stripping URL parameters from the end and replacing the
|
||
@code{:base-url} with @code{:working-directory} and @code{:online-suffix} with
|
||
@code{:working-suffix}. For example, assuming you own a local copy of
|
||
@samp{https://orgmode.org/worg/} contents at @samp{/home/user/worg}, you can set
|
||
@code{org-protocol-project-alist} to the following
|
||
|
||
@lisp
|
||
(setq org-protocol-project-alist
|
||
'(("Worg"
|
||
:base-url "https://orgmode.org/worg/"
|
||
:working-directory "/home/user/worg/"
|
||
:online-suffix ".html"
|
||
:working-suffix ".org")))
|
||
@end lisp
|
||
|
||
@noindent
|
||
If you are now browsing
|
||
@samp{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.
|
||
|
||
@cindex rewritten URL in open-source protocol
|
||
@cindex protocol, open-source rewritten URL
|
||
However, such mapping may not yield the desired results. Suppose you
|
||
maintain an online store located at @samp{http://example.com/}. The local
|
||
sources reside in @samp{/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 @samp{http://example.com/print/posters.html} might be rewritten on the
|
||
server to something like
|
||
@samp{http://example.com/shop/products.php/posters.html.php}. The
|
||
@code{open-source} handler probably cannot find a file named
|
||
@samp{/home/user/example/print/posters.html.php} and fails.
|
||
|
||
Such an entry in @code{org-protocol-project-alist} may hold an additional
|
||
property @code{:rewrites}. This property is a list of cons cells, each of
|
||
which maps a regular expression to a path relative to the
|
||
@code{:working-directory}.
|
||
|
||
Now map the URL to the path @samp{/home/user/example/products.php} by
|
||
adding @code{:rewrites} rules like this:
|
||
|
||
@lisp
|
||
(setq org-protocol-project-alist
|
||
'(("example.com"
|
||
:base-url "http://example.com/"
|
||
:working-directory "/home/user/example/"
|
||
:online-suffix ".php"
|
||
:working-suffix ".php"
|
||
:rewrites (("example.com/print/" . "products.php")
|
||
("example.com/$" . "index.php")))))
|
||
@end lisp
|
||
|
||
@noindent
|
||
Since @samp{example.com/$} is used as a regular expression, it maps
|
||
@samp{http://example.com/}, @samp{https://example.com},
|
||
@samp{http://www.example.com/} and similar to
|
||
@samp{/home/user/example/index.php}.
|
||
|
||
The @code{:rewrites} rules are searched as a last resort if and only if no
|
||
existing file name is matched.
|
||
|
||
@cindex protocol, open-source, set-up mapping
|
||
@cindex mappings in open-source protocol
|
||
@findex org-protocol-create
|
||
@findex org-protocol-create-for-org
|
||
Two functions can help you filling @code{org-protocol-project-alist} with
|
||
valid contents: @code{org-protocol-create} and
|
||
@code{org-protocol-create-for-org}. The latter is of use if you're editing
|
||
an Org file that is part of a publishing project.
|
||
|
||
@node Refile and Copy
|
||
@section Refile and Copy
|
||
|
||
@cindex refiling notes
|
||
@cindex copying notes
|
||
|
||
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:
|
||
|
||
@table @asis
|
||
@item @kbd{C-c M-w} (@code{org-copy})
|
||
@kindex C-c M-w
|
||
@findex org-copy
|
||
Copying works like refiling, except that the original note is not
|
||
deleted.
|
||
|
||
@item @kbd{C-c C-w} (@code{org-refile})
|
||
@kindex C-c C-w
|
||
@findex org-refile
|
||
@vindex org-reverse-note-order
|
||
@vindex org-refile-targets
|
||
@vindex org-refile-use-outline-path
|
||
@vindex org-outline-path-complete-in-steps
|
||
@vindex org-refile-allow-creating-parent-nodes
|
||
@vindex org-log-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
|
||
@code{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
|
||
@code{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 @code{org-refile-use-outline-path} and
|
||
@code{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 @code{org-refile-allow-creating-parent-nodes}.
|
||
When the variable @code{org-log-refile}@footnote{Note the corresponding @samp{STARTUP} options @samp{logrefile},
|
||
@samp{lognoterefile}, and @samp{nologrefile}.} is set, a timestamp or
|
||
a note is recorded whenever an entry is refiled.
|
||
|
||
@item @kbd{C-u C-c C-w}
|
||
@kindex C-u C-c C-w
|
||
Use the refile interface to jump to a heading.
|
||
|
||
@item @kbd{C-u C-u C-c C-w} (@code{org-refile-goto-last-stored})
|
||
@kindex C-u C-u C-c C-w
|
||
@findex org-refile-goto-last-stored
|
||
Jump to the location where @code{org-refile} last moved a tree to.
|
||
|
||
@item @kbd{C-2 C-c C-w}
|
||
@kindex C-2 C-c C-w
|
||
Refile as the child of the item currently being clocked.
|
||
|
||
@item @kbd{C-3 C-c C-w}
|
||
@kindex C-3 C-c C-w
|
||
@vindex org-refile-keep
|
||
Refile and keep the entry in place. Also see @code{org-refile-keep}
|
||
to make this the default behavior, and beware that this may
|
||
result in duplicated @code{ID} properties.
|
||
|
||
@item @kbd{C-0 C-c C-w} or @kbd{C-u C-u C-u C-c C-w} (@code{org-refile-cache-clear})
|
||
@kindex C-u C-u C-u C-c C-w
|
||
@kindex C-0 C-c C-w
|
||
@findex org-refile-cache-clear
|
||
@vindex org-refile-use-cache
|
||
Clear the target cache. Caching of refile targets can be turned
|
||
on by setting @code{org-refile-use-cache}. To make the command see
|
||
new possible targets, you have to clear the cache with this
|
||
command.
|
||
@end table
|
||
|
||
@node Archiving
|
||
@section Archiving
|
||
|
||
@cindex 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.
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-x C-a} (@code{org-archive-subtree-default})
|
||
@kindex C-c C-x C-a
|
||
@findex org-archive-subtree-default
|
||
@vindex org-archive-default-command
|
||
Archive the current entry using the command specified in the
|
||
variable @code{org-archive-default-command}.
|
||
@end table
|
||
|
||
@menu
|
||
* Moving subtrees:: Moving a tree to an archive file.
|
||
* Internal archiving:: Switch off a tree but keep it in the file.
|
||
@end menu
|
||
|
||
@node Moving subtrees
|
||
@subsection Moving a tree to an archive file
|
||
|
||
@cindex external archiving
|
||
|
||
The most common archiving action is to move a project tree to another
|
||
file, the archive file.
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-x C-s} or short @kbd{C-c $} (@code{org-archive-subtree})
|
||
@kindex C-c C-x C-s
|
||
@kindex C-c $
|
||
@findex org-archive-subtree
|
||
@vindex org-archive-location
|
||
Archive the subtree starting at the cursor position to the
|
||
location given by @code{org-archive-location}.
|
||
|
||
@item @kbd{C-u C-c C-x C-s}
|
||
@kindex 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 the cursor is @emph{not} on a headline when
|
||
this command is invoked, check level 1 trees.
|
||
|
||
@item @kbd{C-u C-u C-c C-x C-s}
|
||
@kindex 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 @emph{does}
|
||
contain a timestamp, and that timestamp is in the past.
|
||
@end table
|
||
|
||
@cindex archive locations
|
||
The default archive location is a file in the same directory as the
|
||
current file, with the name derived by appending @samp{_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
|
||
@code{org-archive-location}.
|
||
|
||
There is also an in-buffer option for setting this variable, for
|
||
example:
|
||
|
||
@cindex @samp{ARCHIVE}, keyword
|
||
@example
|
||
#+ARCHIVE: %s_done::
|
||
@end example
|
||
|
||
@noindent
|
||
@cindex ARCHIVE, property
|
||
If you would like to have a special archive location for a single
|
||
entry or a (sub)tree, give the entry an @samp{ARCHIVE} property with the
|
||
location as the value (see @ref{Properties and Columns}).
|
||
|
||
@vindex org-archive-save-context-info
|
||
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
|
||
@code{org-archive-save-context-info} to adjust the amount of information
|
||
added.
|
||
|
||
@node Internal archiving
|
||
@subsection Internal archiving
|
||
|
||
@cindex @samp{ARCHIVE}, tag
|
||
If you want to just switch off---for agenda views---certain subtrees
|
||
without moving them to a different file, you can use the @samp{ARCHIVE}
|
||
tag.
|
||
|
||
A headline that is marked with the @samp{ARCHIVE} tag (see @ref{Tags}) stays at
|
||
its location in the outline tree, but behaves in the following way:
|
||
|
||
@itemize
|
||
@item
|
||
@vindex org-cycle-open-archived-trees
|
||
It does not open when you attempt to do so with a visibility cycling
|
||
command (see @ref{Visibility Cycling}). You can force cycling archived
|
||
subtrees with @kbd{C-@key{TAB}}, or by setting the option
|
||
@code{org-cycle-open-archived-trees}. Also normal outline commands, like
|
||
@code{outline-show-all}, open archived subtrees.
|
||
|
||
@item
|
||
@vindex org-sparse-tree-open-archived-trees
|
||
During sparse tree construction (see @ref{Sparse Trees}), matches in
|
||
archived subtrees are not exposed, unless you configure the option
|
||
@code{org-sparse-tree-open-archived-trees}.
|
||
|
||
@item
|
||
@vindex org-agenda-skip-archived-trees
|
||
During agenda view construction (see @ref{Agenda Views}), the content of
|
||
archived trees is ignored unless you configure the option
|
||
@code{org-agenda-skip-archived-trees}, in which case these trees are
|
||
always included. In the agenda you can press @kbd{v a} to get
|
||
archives temporarily included.
|
||
|
||
@item
|
||
@vindex org-export-with-archived-trees
|
||
Archived trees are not exported (see @ref{Exporting}), only the headline
|
||
is. Configure the details using the variable
|
||
@code{org-export-with-archived-trees}.
|
||
|
||
@item
|
||
@vindex org-columns-skip-archived-trees
|
||
Archived trees are excluded from column view unless the variable
|
||
@code{org-columns-skip-archived-trees} is configured to @code{nil}.
|
||
@end itemize
|
||
|
||
The following commands help manage the @samp{ARCHIVE} tag:
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-x a} (@code{org-toggle-archive-tag})
|
||
@kindex C-c C-x a
|
||
@findex 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.
|
||
|
||
@item @kbd{C-u C-c C-x a}
|
||
@kindex 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 @samp{ARCHIVE} tag for
|
||
the child. If the cursor is @emph{not} on a headline when this
|
||
command is invoked, check the level 1 trees.
|
||
|
||
@item @kbd{C-@key{TAB}}, @code{org-force-cycle-archived}
|
||
@kindex C-TAB
|
||
Cycle a tree even if it is tagged with @samp{ARCHIVE}.
|
||
|
||
@item @kbd{C-c C-x A} (@code{org-archive-to-archive-sibling})
|
||
@kindex C-c C-x A
|
||
@findex org-archive-to-archive-sibling
|
||
Move the current entry to the @emph{Archive Sibling}. This is
|
||
a sibling of the entry with the heading @samp{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.
|
||
@end table
|
||
|
||
@node Agenda Views
|
||
@chapter Agenda Views
|
||
|
||
@cindex 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. Seven different view types are provided:
|
||
|
||
@itemize
|
||
@item
|
||
an @emph{agenda} that is like a calendar and shows information for
|
||
specific dates,
|
||
|
||
@item
|
||
a @emph{TODO list} that covers all unfinished action items,
|
||
|
||
@item
|
||
a @emph{match view}, showings headlines based on the tags, properties,
|
||
and TODO state associated with them,
|
||
|
||
@item
|
||
a @emph{timeline view} that shows all events in a single Org file, in
|
||
time-sorted view,
|
||
|
||
@item
|
||
a @emph{text search view} that shows all entries from multiple files that
|
||
contain specified keywords,
|
||
|
||
@item
|
||
a @emph{stuck projects view} showing projects that currently do not move
|
||
along, and
|
||
|
||
@item
|
||
@emph{custom views} that are special searches and combinations of
|
||
different views.
|
||
@end itemize
|
||
|
||
@noindent
|
||
The extracted information is displayed in a special @emph{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.
|
||
|
||
@vindex org-agenda-skip-comment-trees
|
||
@vindex org-agenda-skip-archived-trees
|
||
@cindex commented entries, in agenda views
|
||
@cindex archived entries, in agenda views
|
||
By default, the report ignores commented (see @ref{Comment Lines}) and
|
||
archived (see @ref{Internal archiving}) entries. You can override this by
|
||
setting @code{org-agenda-skip-comment-trees} and
|
||
@code{org-agenda-skip-archived-trees} to @code{nil}.
|
||
|
||
@vindex org-agenda-window-setup
|
||
@vindex org-agenda-restore-windows-after-quit
|
||
Two variables control how the agenda buffer is displayed and whether
|
||
the window configuration is restored when the agenda exits:
|
||
@code{org-agenda-window-setup} and @code{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.
|
||
@end menu
|
||
|
||
@node Agenda Files
|
||
@section Agenda Files
|
||
|
||
@cindex agenda files
|
||
@cindex files for agenda
|
||
|
||
@vindex org-agenda-files
|
||
The information to be shown is normally collected from all @emph{agenda
|
||
files}, the files listed in the variable @code{org-agenda-files}@footnote{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.}.
|
||
If a directory is part of this list, all files with the extension
|
||
@samp{.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@footnote{When using the dispatcher, pressing @kbd{<} before
|
||
selecting a command actually limits the command to the current file,
|
||
and ignores @code{org-agenda-files} until the next dispatcher command.}. You can customize @code{org-agenda-files},
|
||
but the easiest way to maintain it is through the following commands
|
||
|
||
@table @asis
|
||
@item @kbd{C-c [} (@code{org-agenda-file-to-front})
|
||
@kindex C-c [
|
||
@findex org-agenda-file-to-front
|
||
@cindex files, adding to agenda list
|
||
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.
|
||
|
||
@item @kbd{C-c ]} (@code{org-remove-file})
|
||
@kindex C-c ]
|
||
@findex org-remove-file
|
||
Remove current file from the list of agenda files.
|
||
|
||
@item @kbd{C-'}
|
||
@itemx @kbd{C-,} (@code{org-cycle-agenda-files})
|
||
@kindex C-'
|
||
@kindex C-,
|
||
@findex org-cycle-agenda-files
|
||
@cindex cycling, of agenda files
|
||
Cycle through agenda file list, visiting one file after the other.
|
||
|
||
@item @kbd{M-x org-switchb}
|
||
@findex org-switchb
|
||
Command to use an iswitchb-like interface to switch to and
|
||
between Org buffers.
|
||
@end table
|
||
|
||
@noindent
|
||
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 @kbd{<} once or several times in
|
||
the dispatcher (see @ref{Agenda Dispatcher}). To restrict the agenda
|
||
scope for an extended period, use the following commands:
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-x <} (@code{org-agenda-set-restriction-lock})
|
||
@kindex C-c C-x <
|
||
@findex org-agenda-set-restriction-lock
|
||
Permanently restrict the agenda to the current subtree. When
|
||
called with a prefix argument, or with the cursor before the
|
||
first headline in a file, set the agenda scope to the entire
|
||
file. This restriction remains in effect until removed with
|
||
@kbd{C-c C-x >}, or by typing either @kbd{<} or
|
||
@kbd{>} in the agenda dispatcher. If there is a window
|
||
displaying an agenda view, the new restriction takes effect
|
||
immediately.
|
||
|
||
@item @kbd{C-c C-x >} (@code{org-agenda-remove-restriction-lock})
|
||
@kindex C-c C-x >
|
||
@findex org-agenda-remove-restriction-lock
|
||
Remove the permanent restriction created by @kbd{C-c C-x <}.
|
||
@end table
|
||
|
||
@noindent
|
||
When working with @samp{speedbar.el}, you can use the following commands in
|
||
the Speedbar frame:
|
||
|
||
@table @asis
|
||
@item @kbd{<} (@code{org-speedbar-set-agenda-restriction})
|
||
@findex org-speedbar-set-agenda-restriction
|
||
Permanently restrict the agenda to the item---either an Org file
|
||
or a subtree in such a file---at the cursor in the Speedbar
|
||
frame. If there is a window displaying an agenda view, the new
|
||
restriction takes effect immediately.
|
||
|
||
@item @kbd{>} (@code{org-agenda-remove-restriction-lock})
|
||
@findex org-agenda-remove-restriction-lock
|
||
Lift the restriction.
|
||
@end table
|
||
|
||
@node Agenda Dispatcher
|
||
@section The Agenda Dispatcher
|
||
|
||
@cindex agenda dispatcher
|
||
@cindex dispatching agenda commands
|
||
|
||
The views are created through a dispatcher, accessible with @kbd{M-x org-agenda}, or, better, bound to a global key (see @ref{Activation}).
|
||
It displays a menu from which an additional letter is required to
|
||
execute a command. The dispatcher offers the following default
|
||
commands:
|
||
|
||
@table @asis
|
||
@item @kbd{a}
|
||
Create the calendar-like agenda (see @ref{Weekly/daily agenda}).
|
||
|
||
@item @kbd{t} or @kbd{T}
|
||
Create a list of all TODO items (see @ref{Global TODO list}).
|
||
|
||
@item @kbd{m} or @kbd{M}
|
||
Create a list of headlines matching a given expression (see
|
||
@ref{Matching tags and properties}).
|
||
|
||
@item @kbd{s}
|
||
@kindex s @r{(Agenda dispatcher)}
|
||
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.
|
||
|
||
@item @kbd{/}
|
||
@kindex / @r{(Agenda dispatcher)}
|
||
@vindex org-agenda-text-search-extra-files
|
||
Search for a regular expression in all agenda files and
|
||
additionally in the files listed in
|
||
@code{org-agenda-text-search-extra-files}. This uses the Emacs
|
||
command @code{multi-occur}. A prefix argument can be used to specify
|
||
the number of context lines for each match, default is
|
||
@enumerate
|
||
@item
|
||
@end enumerate
|
||
|
||
@item @kbd{#} or @kbd{!}
|
||
Create a list of stuck projects (see @ref{Stuck projects}).
|
||
|
||
@item @kbd{<}
|
||
@kindex < @r{(Agenda dispatcher)}
|
||
Restrict an agenda command to the current buffer@footnote{For backward compatibility, you can also press @kbd{1} to
|
||
restrict to the current buffer.}. After
|
||
pressing @kbd{<}, you still need to press the character
|
||
selecting the command.
|
||
|
||
@item @kbd{< <}
|
||
@kindex < < @r{(Agenda dispatcher)}
|
||
If there is an active region, restrict the following agenda
|
||
command to the region. Otherwise, restrict it to the current
|
||
subtree@footnote{For backward compatibility, you can also press @kbd{0} to
|
||
restrict to the current region/subtree.}. After pressing @kbd{< <}, you still need to
|
||
press the character selecting the command.
|
||
|
||
@item @kbd{*}
|
||
@kindex * @r{(Agenda dispatcher)}
|
||
@vindex org-agenda-sticky
|
||
@findex org-toggle-sticky-agenda
|
||
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 @code{org-agenda-sticky}). With sticky
|
||
agendas, the dispatcher only switches to the selected view, you
|
||
need to update it by hand with @kbd{r} or @kbd{g}. You
|
||
can toggle sticky agenda view any time with
|
||
@code{org-toggle-sticky-agenda}.
|
||
@end table
|
||
|
||
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 @ref{Custom Agenda Views}.
|
||
|
||
@node Built-in Agenda Views
|
||
@section 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.
|
||
@end menu
|
||
|
||
@node Weekly/daily agenda
|
||
@subsection Weekly/daily agenda
|
||
|
||
@cindex agenda
|
||
@cindex weekly agenda
|
||
@cindex daily agenda
|
||
|
||
The purpose of the weekly/daily @emph{agenda} is to act like a page of
|
||
a paper agenda, showing all the tasks for the current week or day.
|
||
|
||
@table @asis
|
||
@item @kbd{M-x org-agenda a} (@code{org-agenda-list})
|
||
@kindex a @r{(Agenda dispatcher)}
|
||
@findex org-agenda-list
|
||
@cindex org-agenda, command
|
||
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@footnote{For backward compatibility, the universal prefix argument
|
||
@kbd{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 @ref{Block agenda}).}---like @kbd{C-u 2 1 M-x org-agenda a}---you
|
||
may set the number of days to be displayed.
|
||
@end table
|
||
|
||
@vindex org-agenda-span
|
||
@vindex org-agenda-start-day
|
||
@vindex org-agenda-start-on-weekday
|
||
The default number of days displayed in the agenda is set by the
|
||
variable @code{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 @code{day}, @code{week}, @code{month} or @code{year}. For weekly agendas, the default
|
||
is to start on the previous Monday (see
|
||
@code{org-agenda-start-on-weekday}). You can also set the start date using
|
||
a date shift: @code{(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 @ref{Agenda Commands}.
|
||
|
||
@anchor{Calendar/Diary integration}
|
||
@subsubheading Calendar/Diary integration
|
||
|
||
@cindex calendar integration
|
||
@cindex 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
|
||
|
||
@lisp
|
||
(setq org-agenda-include-diary t)
|
||
@end lisp
|
||
|
||
@noindent
|
||
After that, everything happens automatically. All diary entries
|
||
including holidays, anniversaries, etc., are included in the agenda
|
||
buffer created by Org mode. @kbd{@key{SPC}}, @kbd{@key{TAB}}, and
|
||
@kbd{@key{RET}} can be used from the agenda buffer to jump to the diary
|
||
file in order to edit existing diary entries. The @kbd{i}
|
||
command to insert new entries for the current date works in the agenda
|
||
buffer, as well as the commands @kbd{S}, @kbd{M}, and
|
||
@kbd{C} to display Sunrise/Sunset times, show lunar phases and to
|
||
convert to other calendars, respectively. @kbd{c} can be used to
|
||
switch back and forth between calendar and agenda.
|
||
|
||
If you are using the diary only for S-exp 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 sexp
|
||
entries, and does it faster because there is no overhead for first
|
||
creating the diary display. Note that the sexp entries must start at
|
||
the left margin, no whitespace is allowed before them, as seen in the
|
||
following segment of an Org file:@footnote{The variable @code{org-anniversary} used in the example is just
|
||
like @code{diary-anniversary}, but the argument order is always according
|
||
to ISO and therefore independent of the value of
|
||
@code{calendar-date-style}.}
|
||
|
||
@example
|
||
* 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
|
||
@end example
|
||
|
||
@anchor{Anniversaries from BBDB}
|
||
@subsubheading Anniversaries from BBDB
|
||
|
||
@cindex BBDB, anniversaries
|
||
@cindex anniversaries, from BBDB
|
||
|
||
@findex org-bbdb-anniversaries
|
||
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:
|
||
|
||
@example
|
||
* Anniversaries
|
||
:PROPERTIES:
|
||
:CATEGORY: Anniv
|
||
:END:
|
||
%%(org-bbdb-anniversaries)
|
||
@end example
|
||
|
||
You can then go ahead and define anniversaries for a BBDB record.
|
||
Basically, you need to press @kbd{C-o anniversary @key{RET}} with the
|
||
cursor in a BBDB record and then add the date in the format
|
||
@samp{YYYY-MM-DD} or @samp{MM-DD}, followed by a space and the class of the
|
||
anniversary (@samp{birthday}, @samp{wedding}, or a format string). If you omit
|
||
the class, it defaults to @samp{birthday}. Here are a few examples, the
|
||
header for the file @samp{org-bbdb.el} contains more detailed information.
|
||
|
||
@example
|
||
1973-06-22
|
||
06-22
|
||
1955-08-02 wedding
|
||
2008-04-14 %s released version 6.01 of Org mode, %d years ago
|
||
@end example
|
||
|
||
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
|
||
@samp{%%(diary-anniversary)} entries in an Org or Diary file.
|
||
|
||
@findex org-bbdb-anniversaries-future
|
||
If you would like to see upcoming anniversaries with a bit of
|
||
forewarning, you can use the following instead:
|
||
|
||
@example
|
||
* Anniversaries
|
||
:PROPERTIES:
|
||
:CATEGORY: Anniv
|
||
:END:
|
||
%%(org-bbdb-anniversaries-future 3)
|
||
@end example
|
||
|
||
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.
|
||
|
||
@anchor{Appointment reminders}
|
||
@subsubheading Appointment reminders
|
||
|
||
@cindex @file{appt.el}
|
||
@cindex appointment reminders
|
||
@cindex appointment
|
||
@cindex reminders
|
||
|
||
@cindex APPT_WARNTIME, keyword
|
||
Org can interact with Emacs appointments notification facility. To
|
||
add the appointments of your agenda files, use the command
|
||
@code{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 @samp{APPT_WARNTIME} property which overrides the value of
|
||
@code{appt-message-warning-time} for this appointment. See the docstring
|
||
for details.
|
||
|
||
@node Global TODO list
|
||
@subsection The global TODO list
|
||
|
||
@cindex global TODO list
|
||
@cindex TODO list, global
|
||
|
||
The global TODO list contains all unfinished TODO items formatted and
|
||
collected into a single place.
|
||
|
||
@table @asis
|
||
@item @kbd{M-x org-agenda t} (@code{org-todo-list})
|
||
@kindex t @r{(Agenda dispatcher)}
|
||
@findex org-todo-list
|
||
Show the global TODO list. This collects the TODO items from all
|
||
agenda files (see @ref{Agenda Views}) into a single buffer. By
|
||
default, this lists items with a state the is not a DONE state.
|
||
The buffer is in @code{agenda-mode}, so there are commands to examine
|
||
and manipulate the TODO entries directly from that buffer (see
|
||
@ref{Agenda Commands}).
|
||
|
||
@item @kbd{M-x org-agenda T} (@code{org-todo-list})
|
||
@kindex T @r{(Agenda dispatcher)}
|
||
@findex org-todo-list
|
||
@cindex TODO keyword matching
|
||
@vindex org-todo-keywords
|
||
Like the above, but allows selection of a specific TODO keyword.
|
||
You can also do this by specifying a prefix argument to
|
||
@kbd{t}. You are prompted for a keyword, and you may also
|
||
specify several keywords by separating them with @samp{|} as the
|
||
boolean OR operator. With a numeric prefix, the Nth keyword in
|
||
@code{org-todo-keywords} is selected.
|
||
|
||
@kindex r
|
||
The @kbd{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 @kbd{3 r}. If you often need
|
||
a search for a specific keyword, define a custom command for it
|
||
(see @ref{Agenda Dispatcher}).
|
||
|
||
Matching specific TODO keywords can also be done as part of
|
||
a tags search (see @ref{Tag Searches}).
|
||
@end table
|
||
|
||
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 @ref{Agenda Commands}.
|
||
|
||
@cindex sublevels, inclusion into TODO list
|
||
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:
|
||
|
||
@itemize
|
||
@item
|
||
@vindex org-agenda-todo-ignore-scheduled
|
||
@vindex org-agenda-todo-ignore-deadlines
|
||
@vindex org-agenda-todo-ignore-timestamp
|
||
@vindex org-agenda-todo-ignore-with-date
|
||
Some people view a TODO item that has been @emph{scheduled} for execution
|
||
or have a @emph{deadline} (see @ref{Timestamps}) as
|
||
no longer @emph{open}. Configure the variables
|
||
@code{org-agenda-todo-ignore-scheduled},
|
||
@code{org-agenda-todo-ignore-deadlines},
|
||
@code{org-agenda-todo-ignore-timestamp} and/or
|
||
@code{org-agenda-todo-ignore-with-date} to exclude such items from the
|
||
global TODO list.
|
||
|
||
@item
|
||
@vindex org-agenda-todo-list-sublevels
|
||
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 @code{org-agenda-todo-list-sublevels} to get this behavior.
|
||
@end itemize
|
||
|
||
@node Matching tags and properties
|
||
@subsection Matching tags and properties
|
||
|
||
@cindex matching, of tags
|
||
@cindex matching, of properties
|
||
@cindex tags view
|
||
@cindex match view
|
||
|
||
If headlines in the agenda files are marked with @emph{tags} (see @ref{Tags}),
|
||
or have properties (see @ref{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 @kbd{C-c / m}.
|
||
|
||
@table @asis
|
||
@item @kbd{M-x org-agenda m} (@code{org-tags-view})
|
||
@kindex m @r{(Agenda dispatcher)}
|
||
@findex 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 @samp{+work+urgent-withboss} or
|
||
@samp{work|home} (see @ref{Tags}). If you often need a specific search,
|
||
define a custom command for it (see @ref{Agenda Dispatcher}).
|
||
|
||
@item @kbd{M-x org-agenda M} (@code{org-tags-view})
|
||
@kindex M @r{(Agenda dispatcher)}
|
||
@findex org-tags-view
|
||
@vindex org-tags-match-list-sublevels
|
||
@vindex org-agenda-tags-todo-honor-ignore-options
|
||
Like @kbd{m}, but only select headlines that are also TODO
|
||
items and force checking subitems (see the variable
|
||
@code{org-tags-match-list-sublevels}). To exclude scheduled/deadline
|
||
items, see the variable
|
||
@code{org-agenda-tags-todo-honor-ignore-options}. Matching specific
|
||
TODO keywords together with a tags match is also possible, see
|
||
@ref{Tag Searches}.
|
||
@end table
|
||
|
||
The commands available in the tags list are described in @ref{Agenda Commands}.
|
||
|
||
@cindex boolean logic, for agenda searches
|
||
A search string can use Boolean operators @samp{&} for AND and @samp{|} for OR.
|
||
@samp{&} binds more strongly than @samp{|}. Parentheses are currently not
|
||
implemented. Each element in the search is either a tag, a regular
|
||
expression matching tags, or an expression like @samp{PROPERTY OPERATOR
|
||
VALUE} with a comparison operator, accessing a property value. Each
|
||
element may be preceded by @samp{-} to select against it, and @samp{+} is
|
||
syntactic sugar for positive selection. The AND operator @samp{&} is
|
||
optional when @samp{+} or @samp{-} is present. Here are some examples, using
|
||
only tags.
|
||
|
||
@table @asis
|
||
@item @code{+work-boss}
|
||
Select headlines tagged @samp{work}, but discard those also tagged
|
||
@samp{boss}.
|
||
|
||
@item @code{work|laptop}
|
||
Selects lines tagged @samp{work} or @samp{laptop}.
|
||
|
||
@item @code{work|laptop+night}
|
||
Like before, but require the @samp{laptop} lines to be tagged
|
||
also @samp{night}.
|
||
@end table
|
||
|
||
@cindex regular expressions, with tags search
|
||
Instead of a tag, you may also specify a regular expression enclosed
|
||
in curly braces. For example, @samp{work+@{^boss.*@}} matches headlines that
|
||
contain the tag @samp{:work:} and any tag @emph{starting} with @samp{boss}.
|
||
|
||
@cindex group tags, as regular expressions
|
||
Group tags (see @ref{Tag Hierarchy}) are expanded as regular expressions.
|
||
E.g., if @samp{work} is a group tag for the group @samp{:work:lab:conf:}, then
|
||
searching for @samp{work} also searches for @samp{@{\(?:work\|lab\|conf\)@}} and
|
||
searching for @samp{-work} searches for all headlines but those with one of
|
||
the tags in the group (i.e., @samp{-@{\(?:work\|lab\|conf\)@}}).
|
||
|
||
@cindex TODO keyword matching, with tags search
|
||
@cindex level, for tags/property match
|
||
@cindex category, for tags/property match
|
||
@vindex org-odd-levels-only
|
||
You may also test for properties (see @ref{Properties and Columns}) at the
|
||
same time as matching tags. The properties may be real properties, or
|
||
special properties that represent other metadata (see @ref{Special Properties}). For example, the property @samp{TODO} represents the TODO
|
||
keyword of the entry. Or, the property @samp{LEVEL} represents the level
|
||
of an entry. So searching @samp{+LEVEL=3+boss-TODO="DONE"} lists all level
|
||
three headlines that have the tag @samp{boss} and are @emph{not} marked with the
|
||
TODO keyword @samp{DONE}. In buffers with @code{org-odd-levels-only} set,
|
||
@samp{LEVEL} does not count the number of stars, but @samp{LEVEL=2} corresponds
|
||
to 3 stars etc.
|
||
|
||
Here are more examples:
|
||
|
||
@table @asis
|
||
@item @samp{work+TODO="WAITING"}
|
||
Select @samp{work}-tagged TODO lines with the specific TODO keyword
|
||
@samp{WAITING}.
|
||
|
||
@item @samp{work+TODO="WAITING"|home+TODO="WAITING"}
|
||
Waiting tasks both at work and at home.
|
||
@end table
|
||
|
||
When matching properties, a number of different operators can be used
|
||
to test the value of a property. Here is a complex example:
|
||
|
||
@example
|
||
+work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<2
|
||
+With=@{Sarah|Denny@}+SCHEDULED>="<2008-10-11>"
|
||
@end example
|
||
|
||
@noindent
|
||
The type of comparison depends on how the comparison value is written:
|
||
|
||
@itemize
|
||
@item
|
||
If the comparison value is a plain number, a numerical comparison is
|
||
done, and the allowed operators are @samp{<}, @samp{=}, @samp{>}, @samp{<=}, @samp{>=}, and
|
||
@samp{<>}.
|
||
|
||
@item
|
||
If the comparison value is enclosed in double-quotes, a string
|
||
comparison is done, and the same operators are allowed.
|
||
|
||
@item
|
||
If the comparison value is enclosed in double-quotes @emph{and} angular
|
||
brackets (like @samp{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
|
||
@samp{"<now>"} for now (including time), @samp{"<today>"}, and @samp{"<tomorrow>"}
|
||
for these days at 0:00 hours, i.e., without a time specification.
|
||
You can also use strings like @samp{"<+5d>"} or @samp{"<-2m>"} with units @samp{d},
|
||
@samp{w}, @samp{m}, and @samp{y} for day, week, month, and year, respectively.
|
||
|
||
@item
|
||
If the comparison value is enclosed in curly braces, a regexp match
|
||
is performed, with @samp{=} meaning that the regexp matches the property
|
||
value, and @samp{<>} meaning that it does not match.
|
||
@end itemize
|
||
|
||
So the search string in the example finds entries tagged @samp{work} but
|
||
not @samp{boss}, which also have a priority value @samp{A}, a @samp{Coffee} property
|
||
with the value @samp{unlimited}, an @samp{EFFORT} property that is numerically
|
||
smaller than 2, a @samp{With} property that is matched by the regular
|
||
expression @samp{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 @ref{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 @samp{|}) with a @samp{/} 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, @emph{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 @kbd{M-x org-agenda M}, or equivalently start the TODO part after the slash
|
||
with @samp{!}. Using @kbd{M-x org-agenda M} or @samp{/!} does not match
|
||
TODO keywords in a DONE state. Examples:
|
||
|
||
@table @asis
|
||
@item @samp{work/WAITING}
|
||
Same as @samp{work+TODO="WAITING"}.
|
||
|
||
@item @samp{work/!-WAITING-NEXT}
|
||
Select @samp{work}-tagged TODO lines that are neither @samp{WAITING} nor
|
||
@samp{NEXT}.
|
||
|
||
@item @samp{work/!+WAITING|+NEXT}
|
||
Select @samp{work}-tagged TODO lines that are either @samp{WAITING} or
|
||
@samp{NEXT}.
|
||
@end table
|
||
|
||
@node Search view
|
||
@subsection Search view
|
||
|
||
@cindex search view
|
||
@cindex text search
|
||
@cindex searching, for text
|
||
|
||
This agenda view is a general text search facility for Org mode
|
||
entries. It is particularly useful to find notes.
|
||
|
||
@table @asis
|
||
@item @kbd{M-x org-agenda s} (@code{org-search-view})
|
||
@kindex s @r{(Agenda dispatcher)}
|
||
@findex org-search-view
|
||
This is a special search that lets you select entries by matching
|
||
a substring or specific words using a boolean logic.
|
||
@end table
|
||
|
||
For example, the search string @samp{computer equipment} matches entries
|
||
that contain @samp{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 @samp{+computer
|
||
+wifi -ethernet -@{8\.11[bg]@}} matches note entries that contain the
|
||
keywords @samp{computer} and @samp{wifi}, but not the keyword @samp{ethernet}, and
|
||
which are also not matched by the regular expression @samp{8\.11[bg]},
|
||
meaning to exclude both @samp{8.11b} and @samp{8.11g}. The first @samp{+} is
|
||
necessary to turn on boolean search, other @samp{+} characters are
|
||
optional. For more details, see the docstring of the command
|
||
@code{org-search-view}.
|
||
|
||
You can incrementally adjust a boolean search with the following keys
|
||
|
||
@multitable @columnfractions 0.1 0.6
|
||
@item @kbd{[}
|
||
@tab Add a positive search word
|
||
@item @kbd{]}
|
||
@tab Add a negative search word
|
||
@item @kbd{@{}
|
||
@tab Add a positive regular expression
|
||
@item @kbd{@}}
|
||
@tab Add a negative regular expression
|
||
@end multitable
|
||
|
||
@vindex org-agenda-text-search-extra-files
|
||
Note that in addition to the agenda files, this command also searches
|
||
the files listed in @code{org-agenda-text-search-extra-files}.
|
||
|
||
@node Stuck projects
|
||
@subsection Stuck projects
|
||
|
||
@pindex GTD, Getting Things Done
|
||
|
||
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 @emph{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.
|
||
|
||
@table @asis
|
||
@item @kbd{M-x org-agenda #} (@code{org-agenda-list-stuck-projects})
|
||
@kindex # @r{(Agenda dispatcher)}
|
||
@findex org-agenda-list-stuck-projects
|
||
List projects that are stuck.
|
||
|
||
@item @kbd{M-x org-agenda !}
|
||
@kindex ! @r{(Agenda dispatcher)}
|
||
@vindex org-stuck-projects
|
||
Customize the variable @code{org-stuck-projects} to define what
|
||
a stuck project is and how to find it.
|
||
@end table
|
||
|
||
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 @samp{TODO} or @samp{NEXT} or @samp{NEXTACTION}.
|
||
|
||
Let's assume that you, in your own way of using Org mode, identify
|
||
projects with a tag @samp{:PROJECT:}, and that you use a TODO keyword
|
||
@samp{MAYBE} to indicate a project that should not be considered yet.
|
||
Let's further assume that the TODO keyword @samp{DONE} marks finished
|
||
projects, and that @samp{NEXT} and @samp{TODO} indicate next actions. The tag
|
||
@samp{:@@shop:} indicates shopping and is a next action even without the
|
||
NEXT tag. Finally, if the project contains the special word @samp{IGNORE}
|
||
anywhere, it should not be listed either. In this case you would
|
||
start by identifying eligible projects with a tags/TODO match (see
|
||
@ref{Tag Searches}) @samp{+PROJECT/-MAYBE-DONE}, and then check for @samp{TODO},
|
||
@samp{NEXT}, @samp{@@shop}, and @samp{IGNORE} in the subtree to identify projects that
|
||
are not stuck. The correct customization for this is:
|
||
|
||
@lisp
|
||
(setq org-stuck-projects
|
||
'("+PROJECT/-MAYBE-DONE" ("NEXT" "TODO") ("@@shop")
|
||
"\\<IGNORE\\>"))
|
||
@end lisp
|
||
|
||
Note that if a project is identified as non-stuck, the subtree of this
|
||
entry is searched for stuck projects.
|
||
|
||
@node Presentation and Sorting
|
||
@section Presentation and Sorting
|
||
|
||
@cindex presentation, of agenda items
|
||
|
||
@vindex org-agenda-prefix-format
|
||
@vindex org-agenda-tags-column
|
||
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 @emph{prefix} that contains the @emph{category} (see @ref{Categories})
|
||
of the item and other important information. You can customize in
|
||
which column tags are displayed through @code{org-agenda-tags-column}. You
|
||
can also customize the prefix using the option
|
||
@code{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 times:: Dynamically narrow the agenda.
|
||
@end menu
|
||
|
||
@node Categories
|
||
@subsection Categories
|
||
|
||
@cindex category
|
||
@cindex @samp{CATEGORY}, keyword
|
||
|
||
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:
|
||
|
||
@example
|
||
#+CATEGORY: Thesis
|
||
@end example
|
||
|
||
@noindent
|
||
@cindex @samp{CATEGORY}, property
|
||
If you would like to have a special category for a single entry or
|
||
a (sub)tree, give the entry a @samp{CATEGORY} property with the special
|
||
category you want to apply as the value.
|
||
|
||
@noindent
|
||
The display in the agenda buffer looks best if the category is not
|
||
longer than 10 characters.
|
||
|
||
@noindent
|
||
@vindex org-agenda-category-icon-alist
|
||
You can set up icons for category by customizing the
|
||
@code{org-agenda-category-icon-alist} variable.
|
||
|
||
@node Time-of-day specifications
|
||
@subsection Time-of-day specifications
|
||
|
||
@cindex time-of-day specification
|
||
|
||
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
|
||
|
||
@example
|
||
<2005-05-10 Tue 19:00>
|
||
@end example
|
||
|
||
@noindent
|
||
Time ranges can be specified with two timestamps:
|
||
|
||
@example
|
||
<2005-05-10 Tue 20:30>--<2005-05-10 Tue 22:15>
|
||
@end example
|
||
|
||
In the headline of the entry itself, a time(range) may also appear as
|
||
plain text (like @samp{12:45} or a @samp{8:30-1pm}). If the agenda integrates
|
||
the Emacs diary (see @ref{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:
|
||
|
||
@example
|
||
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
|
||
@end example
|
||
|
||
@cindex time grid
|
||
If the agenda is in single-day mode, or for the display of today, the
|
||
timed entries are embedded in a time grid, like
|
||
|
||
@example
|
||
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
|
||
@end example
|
||
|
||
@vindex org-agenda-use-time-grid
|
||
@vindex org-agenda-time-grid
|
||
The time grid can be turned on and off with the variable
|
||
@code{org-agenda-use-time-grid}, and can be configured with
|
||
@code{org-agenda-time-grid}.
|
||
|
||
@node Sorting of agenda items
|
||
@subsection Sorting of agenda items
|
||
|
||
@cindex sorting, of agenda items
|
||
@cindex priorities, of agenda items
|
||
|
||
Before being inserted into a view, the items are sorted. How this is
|
||
done depends on the type of view.
|
||
|
||
@itemize
|
||
@item
|
||
@vindex org-agenda-files
|
||
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 @emph{schedule} for the day. After that, items remain
|
||
grouped in categories, in the sequence given by @code{org-agenda-files}.
|
||
Within each category, items are sorted by priority (see
|
||
@ref{Priorities}), which is composed of the base priority (2000 for
|
||
priority @samp{A}, 1000 for @samp{B}, and 0 for @samp{C}), plus additional
|
||
increments for overdue scheduled or deadline items.
|
||
|
||
@item
|
||
For the TODO list, items remain in the order of categories, but
|
||
within each category, sorting takes place according to priority (see
|
||
@ref{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.
|
||
|
||
@item
|
||
For tags matches, items are not sorted at all, but just appear in
|
||
the sequence in which they are found in the agenda files.
|
||
@end itemize
|
||
|
||
@vindex org-agenda-sorting-strategy
|
||
Sorting can be customized using the variable
|
||
@code{org-agenda-sorting-strategy}, and may also include criteria based on
|
||
the estimated effort of an entry (see @ref{Effort Estimates}).
|
||
|
||
@node Filtering/limiting agenda times
|
||
@subsection Filtering/limiting agenda times
|
||
|
||
Agenda built-in or customized commands are statically defined. Agenda
|
||
filters and limits provide two ways of dynamically narrowing down the
|
||
list of agenda entries: @emph{filters} and @emph{limits}. Filters only act on
|
||
the display of the items, while limits take effect before the list of
|
||
agenda entries is built. Filters are more often used interactively,
|
||
while limits are mostly useful when defined as local variables within
|
||
custom agenda commands.
|
||
|
||
@anchor{Filtering in the agenda}
|
||
@subsubheading Filtering in the agenda
|
||
|
||
@cindex agenda filtering
|
||
@cindex filtering entries, in agenda
|
||
@cindex tag filtering, in agenda
|
||
@cindex category filtering, in agenda
|
||
@cindex top headline filtering, in agenda
|
||
@cindex effort filtering, in agenda
|
||
@cindex query editing, in agenda
|
||
|
||
@table @asis
|
||
@item @kbd{/} (@code{org-agenda-filter-by-tag})
|
||
@findex org-agenda-filter-by-tag
|
||
@vindex org-agenda-tag-filter-preset
|
||
Filter the agenda view with respect to a tag and/or effort
|
||
estimates. The difference between this and a custom agenda
|
||
command is that filtering is very fast, so that you can switch
|
||
quickly between different filters without having to recreate the
|
||
agenda.@footnote{Custom commands can preset a filter by binding the variable
|
||
@code{org-agenda-tag-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.}
|
||
|
||
You are prompted for a tag selection letter; @kbd{@key{SPC}} means
|
||
any tag at all. Pressing @kbd{@key{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. When called with prefix
|
||
argument, remove the entries that @emph{do} have the tag. A second
|
||
@kbd{/} at the prompt turns off the filter and shows any
|
||
hidden entries. Pressing @kbd{+} or @kbd{-} switches
|
||
between filtering and excluding the next tag.
|
||
|
||
@vindex org-agenda-auto-exclude-function
|
||
Org also supports automatic, context-aware tag filtering. If the
|
||
variable @code{org-agenda-auto-exclude-function} is set to
|
||
a user-defined function, that function can decide which tags
|
||
should be excluded from the agenda automatically. Once this is
|
||
set, the @kbd{/} command then accepts @kbd{@key{RET}} as
|
||
a sub-option key and runs the auto exclusion logic. For example,
|
||
let's say you use a @samp{Net} tag to identify tasks which need
|
||
network access, an @samp{Errand} tag for errands in town, and a @samp{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:
|
||
|
||
@lisp
|
||
(defun org-my-auto-exclude-function (tag)
|
||
(and (cond
|
||
((string= tag "Net")
|
||
(/= 0 (call-process "/sbin/ping" nil nil nil
|
||
"-c1" "-q" "-t1" "mail.gnu.org")))
|
||
((or (string= tag "Errand") (string= tag "Call"))
|
||
(let ((hour (nth 2 (decode-time))))
|
||
(or (< hour 8) (> hour 21)))))
|
||
(concat "-" tag)))
|
||
|
||
(setq org-agenda-auto-exclude-function 'org-my-auto-exclude-function)
|
||
@end lisp
|
||
|
||
@item @kbd{<} (@code{org-agenda-filter-by-category})
|
||
@findex org-agenda-filter-by-category
|
||
Filter the current agenda view with respect to the category of
|
||
the item at point. Pressing @kbd{<} another time removes
|
||
this filter. When called with a prefix argument exclude the
|
||
category of the item at point from the agenda.
|
||
|
||
@vindex org-agenda-category-filter-preset
|
||
You can add a filter preset in custom agenda commands through the
|
||
option @code{org-agenda-category-filter-preset}. See @ref{Setting options}.
|
||
|
||
@item @kbd{^} (@code{org-agenda-filter-by-top-headline})
|
||
@findex org-agenda-filter-by-top-headline
|
||
Filter the current agenda view and only display the siblings and
|
||
the parent headline of the one at point.
|
||
|
||
@item @kbd{=} (@code{org-agenda-filter-by-regexp})
|
||
@findex org-agenda-filter-by-regexp
|
||
Filter the agenda view by a regular expression: only show agenda
|
||
entries matching the regular expression the user entered. When
|
||
called with a prefix argument, it filters @emph{out} entries matching
|
||
the regexp. With two universal prefix arguments, it removes all
|
||
the regexp filters, which can be accumulated.
|
||
|
||
@vindex org-agenda-regexp-filter-preset
|
||
You can add a filter preset in custom agenda commands through the
|
||
option @code{org-agenda-regexp-filter-preset}. See @ref{Setting options}.
|
||
|
||
@item @kbd{_} (@code{org-agenda-filter-by-effort})
|
||
@findex org-agenda-filter-by-effort
|
||
Filter the agenda view with respect to effort estimates. You
|
||
first need to set up allowed efforts globally, for example
|
||
|
||
@lisp
|
||
(setq org-global-properties
|
||
'(("Effort_ALL". "0 0:10 0:30 1:00 2:00 3:00 4:00")))
|
||
@end lisp
|
||
|
||
@vindex org-sort-agenda-noeffort-is-high
|
||
You can then filter for an effort by first typing an operator,
|
||
one of @kbd{<}, @kbd{>} and @kbd{=}, and then the
|
||
one-digit index of an effort estimate in your array of allowed
|
||
values, where @kbd{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 @code{org-sort-agenda-noeffort-is-high}.
|
||
|
||
When called with a prefix argument, it removes entries matching
|
||
the condition. With two universal prefix arguments, it clears
|
||
effort filters, which can be accumulated.
|
||
|
||
@vindex org-agenda-effort-filter-preset
|
||
You can add a filter preset in custom agenda commands through the
|
||
option @code{org-agenda-effort-filter-preset}. See @ref{Setting options}.
|
||
|
||
@item @kbd{|} (@code{org-agenda-filter-remove-all})
|
||
Remove all filters in the current agenda view.
|
||
@end table
|
||
|
||
@anchor{Setting limits for the agenda}
|
||
@subsubheading Setting limits for the agenda
|
||
|
||
@cindex limits, in agenda
|
||
|
||
Here is a list of options that you can set, either globally, or
|
||
locally in your custom agenda views (see @ref{Custom Agenda Views}).
|
||
|
||
@table @asis
|
||
@item @code{org-agenda-max-entries}
|
||
@vindex org-agenda-max-entries
|
||
Limit the number of entries.
|
||
|
||
@item @code{org-agenda-max-effort}
|
||
@vindex org-agenda-max-effort
|
||
Limit the duration of accumulated efforts (as minutes).
|
||
|
||
@item @code{org-agenda-max-todos}
|
||
@vindex org-agenda-max-todos
|
||
Limit the number of entries with TODO keywords.
|
||
|
||
@item @code{org-agenda-max-tags}
|
||
@vindex org-agenda-max-tags
|
||
Limit the number of tagged entries.
|
||
@end table
|
||
|
||
When set to a positive integer, each option excludes entries from
|
||
other categories: for example, @code{(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 @code{org-agenda-max-effort}. One
|
||
useful setup is to use @code{org-agenda-max-entries} locally in a custom
|
||
command. For example, this custom command displays the next five
|
||
entries with a @samp{NEXT} TODO keyword.
|
||
|
||
@lisp
|
||
(setq org-agenda-custom-commands
|
||
'(("n" todo "NEXT"
|
||
((org-agenda-max-entries 5)))))
|
||
@end lisp
|
||
|
||
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:
|
||
|
||
@table @asis
|
||
@item @kbd{~} (@code{org-agenda-limit-interactively})
|
||
@findex org-agenda-limit-interactively
|
||
This prompts for the type of limit to apply and its value.
|
||
@end table
|
||
|
||
@node Agenda Commands
|
||
@section Commands in the Agenda Buffer
|
||
|
||
@cindex commands, in 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, the cursor needs to be in the desired line.
|
||
|
||
@anchor{Motion (1)}
|
||
@subheading Motion
|
||
|
||
@cindex motion commands in agenda
|
||
|
||
@table @asis
|
||
@item @kbd{n} (@code{org-agenda-next-line})
|
||
@kindex n
|
||
@findex org-agenda-next-line
|
||
Next line (same as @kbd{@key{DOWN}} and @kbd{C-n}).
|
||
|
||
@item @kbd{p} (@code{org-agenda-previous-line})
|
||
@kindex p
|
||
@findex org-agenda-previous-line
|
||
Previous line (same as @kbd{@key{UP}} and @kbd{C-p}).
|
||
@end table
|
||
|
||
@anchor{View/Go to Org file}
|
||
@subheading View/Go to Org file
|
||
|
||
@cindex view file commands in agenda
|
||
|
||
@table @asis
|
||
@item @kbd{@key{SPC}} or @kbd{mouse-3} (@code{org-agenda-show-and-scroll-up})
|
||
@kindex SPC
|
||
@kindex mouse-3
|
||
@findex 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.
|
||
|
||
@item @kbd{L} (@code{org-agenda-recenter})
|
||
@findex org-agenda-recenter
|
||
Display original location and recenter that window.
|
||
|
||
@item @kbd{@key{TAB}} or @kbd{mouse-2} (@code{org-agenda-goto})
|
||
@kindex TAB
|
||
@kindex mouse-2
|
||
@findex org-agenda-goto
|
||
Go to the original location of the item in another window.
|
||
|
||
@item @kbd{@key{RET}} (@code{org-agenda-switch-to})
|
||
@kindex RET
|
||
@findex org-agenda-switch-to
|
||
Go to the original location of the item and delete other windows.
|
||
|
||
@item @kbd{F} (@code{org-agenda-follow-mode})
|
||
@kindex F
|
||
@findex org-agenda-follow-mode
|
||
@vindex org-agenda-start-with-follow-mode
|
||
Toggle Follow mode. In Follow mode, as you move the cursor
|
||
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
|
||
@code{org-agenda-start-with-follow-mode}.
|
||
|
||
@item @kbd{C-c C-x b} (@code{org-agenda-tree-to-indirect-buffer})
|
||
@kindex C-c C-x b
|
||
@findex 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 @kbd{C-u} prefix, do not remove the previously used
|
||
indirect buffer.
|
||
|
||
@item @kbd{C-c C-o} (@code{org-agenda-open-link})
|
||
@kindex C-c C-o
|
||
@findex 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.
|
||
@end table
|
||
|
||
@anchor{Change display}
|
||
@subheading Change display
|
||
|
||
@cindex change agenda display
|
||
@cindex display changing, in agenda
|
||
|
||
@table @asis
|
||
@item @kbd{A}
|
||
@kindex A
|
||
Interactively select another agenda view and append it to the
|
||
current view.
|
||
|
||
@item @kbd{o}
|
||
@kindex o
|
||
Delete other windows.
|
||
|
||
@item @kbd{v d} or short @kbd{d} (@code{org-agenda-day-view})
|
||
@kindex v d
|
||
@kindex d
|
||
@findex 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, @kbd{32 d} jumps to February 1st.
|
||
When setting day view, a year may be encoded in the prefix
|
||
argument as well. For example, @kbd{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.
|
||
|
||
@item @kbd{v w} or short @kbd{w} (@code{org-agenda-week-view})
|
||
@kindex v w
|
||
@kindex w
|
||
@findex 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 @kbd{9 w} to ISO week number 9.
|
||
When setting week view, a year may be encoded in the prefix
|
||
argument as well. For example, @kbd{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.
|
||
|
||
@item @kbd{v m} (@code{org-agenda-month-view})
|
||
@kindex v m
|
||
@findex 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,
|
||
@kbd{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.
|
||
|
||
@item @kbd{v y} (@code{org-agenda-year-view})
|
||
@kindex v y
|
||
@findex 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.
|
||
|
||
@item @kbd{v @key{SPC}} (@code{org-agenda-reset-view})
|
||
@kindex v SPC
|
||
@findex org-agenda-reset-view
|
||
@vindex org-agenda-span
|
||
Reset the current view to @code{org-agenda-span}.
|
||
|
||
@item @kbd{f} (@code{org-agenda-later})
|
||
@kindex f
|
||
@findex 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.
|
||
|
||
@item @kbd{b} (@code{org-agenda-earlier})
|
||
@kindex b
|
||
@findex org-agenda-earlier
|
||
Go backward in time to display earlier dates.
|
||
|
||
@item @kbd{.} (@code{org-agenda-goto-today})
|
||
@kindex .
|
||
@findex org-agenda-goto-today
|
||
Go to today.
|
||
|
||
@item @kbd{j} (@code{org-agenda-goto-date})
|
||
@kindex j
|
||
@findex org-agenda-goto-date
|
||
Prompt for a date and go there.
|
||
|
||
@item @kbd{J} (@code{org-agenda-clock-goto})
|
||
@kindex J
|
||
@findex org-agenda-clock-goto
|
||
Go to the currently clocked-in task @emph{in the agenda buffer}.
|
||
|
||
@item @kbd{D} (@code{org-agenda-toggle-diary})
|
||
@kindex D
|
||
@findex org-agenda-toggle-diary
|
||
Toggle the inclusion of diary entries. See @ref{Weekly/daily agenda}.
|
||
|
||
@item @kbd{v l} or @kbd{v L} or short @kbd{l} (@code{org-agenda-log-mode})
|
||
@kindex v l
|
||
@kindex l
|
||
@kindex v L
|
||
@findex org-agenda-log-mode
|
||
@vindex org-log-done
|
||
@vindex org-agenda-log-mode-items
|
||
Toggle Logbook mode. In Logbook mode, entries that were marked
|
||
DONE while logging was on (see the variable @code{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
|
||
@code{org-agenda-log-mode-items}. When called with a @kbd{C-u}
|
||
prefix, show all possible logbook entries, including state
|
||
changes. When called with two prefix arguments @kbd{C-u C-u}, show only logging information, nothing else. @kbd{v L} is equivalent to @kbd{C-u v l}.
|
||
|
||
@item @kbd{v [} or short @kbd{[} (@code{org-agenda-manipulate-query-add})
|
||
@kindex v [
|
||
@kindex [
|
||
@findex org-agenda-manipulate-query-add
|
||
Include inactive timestamps into the current view. Only for
|
||
weekly/daily agenda and timeline views.
|
||
|
||
@item @kbd{v a} (@code{org-agenda-archives-mode})
|
||
@kindex v a
|
||
@findex org-agenda-archives-mode
|
||
Toggle Archives mode. In Archives mode, trees that are archived
|
||
(see @ref{Internal archiving}) are also scanned when producing the
|
||
agenda. To exit archives mode, press @kbd{v a} again.
|
||
|
||
@item @kbd{v A}
|
||
@kindex v A
|
||
Toggle Archives mode. Include all archive files as well.
|
||
|
||
@item @kbd{v R} or short @kbd{R} (@code{org-agenda-clockreport-mode})
|
||
@kindex v R
|
||
@kindex R
|
||
@findex org-agenda-clockreport-mode
|
||
@vindex org-agenda-start-with-clockreport-mode
|
||
@vindex org-clock-report-include-clocking-task
|
||
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 @code{org-agenda-start-with-clockreport-mode}. By
|
||
using a prefix argument when toggling this mode (i.e., @kbd{C-u R}), the clock table does not show contributions from entries
|
||
that are hidden by agenda filtering@footnote{Only tags filtering is respected here, effort filtering is
|
||
ignored.}. See also the
|
||
variable @code{org-clock-report-include-clocking-task}.
|
||
|
||
@item @kbd{v c}
|
||
@kindex v c
|
||
@vindex org-agenda-clock-consistency-checks
|
||
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
|
||
@code{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 @kbd{l} to exit
|
||
Logbook mode.
|
||
|
||
@item @kbd{v E} or short @kbd{E} (@code{org-agenda-entry-text-mode})
|
||
@kindex v E
|
||
@kindex E
|
||
@findex org-agenda-entry-text-mode
|
||
@vindex org-agenda-start-with-entry-text-mode
|
||
@vindex org-agenda-entry-text-maxlines
|
||
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 @code{org-agenda-entry-text-maxlines}. Calling this
|
||
command with a numeric prefix argument temporarily modifies that
|
||
number to the prefix value.
|
||
|
||
@item @kbd{G} (@code{org-agenda-toggle-time-grid})
|
||
@kindex G
|
||
@vindex org-agenda-use-time-grid
|
||
@vindex org-agenda-time-grid
|
||
Toggle the time grid on and off. See also the variables
|
||
@code{org-agenda-use-time-grid} and @code{org-agenda-time-grid}.
|
||
|
||
@item @kbd{r} (@code{org-agenda-redo})
|
||
@itemx @kbd{g}
|
||
@kindex r
|
||
@kindex g
|
||
@findex org-agenda-redo
|
||
Recreate the agenda buffer, for example to reflect the changes
|
||
after modification of the timestamps of items with
|
||
@kbd{S-@key{LEFT}} and @kbd{S-@key{RIGHT}}. When the
|
||
buffer is the global TODO list, a prefix argument is interpreted
|
||
to create a selective list for a specific TODO keyword.
|
||
|
||
@item @kbd{C-x C-s} or short @kbd{s} (@code{org-save-all-org-buffers})
|
||
@kindex C-x C-s
|
||
@findex org-save-all-org-buffers
|
||
@kindex s
|
||
Save all Org buffers in the current Emacs session, and also the
|
||
locations of IDs.
|
||
|
||
@item @kbd{C-c C-x C-c} (@code{org-agenda-columns})
|
||
@kindex C-c C-x C-c
|
||
@findex org-agenda-columns
|
||
@vindex org-columns-default-format
|
||
Invoke column view (see @ref{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 @samp{COLUMNS} keyword, or from
|
||
the default variable @code{org-columns-default-format}) is used in the
|
||
agenda.
|
||
|
||
@item @kbd{C-c C-x >} (@code{org-agenda-remove-restriction-lock})
|
||
@kindex C-c C-x >
|
||
@findex org-agenda-remove-restriction-lock
|
||
Remove the restriction lock on the agenda, if it is currently
|
||
restricted to a file or subtree (see @ref{Agenda Files}).
|
||
|
||
@item @kbd{M-@key{UP}} (@code{org-agenda-drag-line-backward})
|
||
@kindex M-UP
|
||
@findex 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.
|
||
|
||
@item @kbd{M-@key{DOWN}} (@code{org-agenda-drag-line-forward})
|
||
@kindex M-DOWN
|
||
@findex org-agenda-drag-line-forward
|
||
Drag the line at point forward one line. With a numeric prefix
|
||
argument, drag forward by that many lines.
|
||
@end table
|
||
|
||
@anchor{Remote editing}
|
||
@subheading Remote editing
|
||
|
||
@cindex remote editing, from agenda
|
||
|
||
@table @asis
|
||
@item @kbd{0--9}
|
||
Digit argument.
|
||
|
||
@item @kbd{C-_} (@code{org-agenda-undo})
|
||
@kindex C-_
|
||
@findex org-agenda-undo
|
||
@cindex undoing remote-editing events
|
||
@cindex remote editing, undo
|
||
Undo a change due to a remote editing command. The change is
|
||
undone both in the agenda buffer and in the remote buffer.
|
||
|
||
@item @kbd{t} (@code{org-agenda-todo})
|
||
@kindex t
|
||
@findex org-agenda-todo
|
||
Change the TODO state of the item, both in the agenda and in the
|
||
original Org file.
|
||
|
||
@item @kbd{C-S-@key{RIGHT}} (@code{org-agenda-todo-nextset})
|
||
@kindex C-S-RIGHT
|
||
@findex org-agenda-todo-nextset
|
||
Switch to the next set of TODO keywords.
|
||
|
||
@item @kbd{C-S-@key{LEFT}}, @code{org-agenda-todo-previousset}
|
||
@kindex C-S-LEFT
|
||
Switch to the previous set of TODO keywords.
|
||
|
||
@item @kbd{C-k} (@code{org-agenda-kill})
|
||
@kindex C-k
|
||
@findex org-agenda-kill
|
||
@vindex org-agenda-confirm-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 @code{org-agenda-confirm-kill}.
|
||
|
||
@item @kbd{C-c C-w} (@code{org-agenda-refile})
|
||
@kindex C-c C-w
|
||
@findex org-agenda-refile
|
||
Refile the entry at point.
|
||
|
||
@item @kbd{C-c C-x C-a} or short @kbd{a} (@code{org-agenda-archive-default-with-confirmation})
|
||
@kindex C-c C-x C-a
|
||
@kindex a
|
||
@findex org-agenda-archive-default-with-confirmation
|
||
@vindex org-archive-default-command
|
||
Archive the subtree corresponding to the entry at point using the
|
||
default archiving command set in @code{org-archive-default-command}.
|
||
When using the @kbd{a} key, confirmation is required.
|
||
|
||
@item @kbd{C-c C-x a} (@code{org-agenda-toggle-archive-tag})
|
||
@kindex C-c C-x a
|
||
@findex org-agenda-toggle-archive-tag
|
||
Toggle the archive tag (see @ref{Internal archiving}) for the current
|
||
headline.
|
||
|
||
@item @kbd{C-c C-x A} (@code{org-agenda-archive-to-archive-sibling})
|
||
@kindex C-c C-x A
|
||
@findex org-agenda-archive-to-archive-sibling
|
||
Move the subtree corresponding to the current entry to its
|
||
@emph{archive sibling}.
|
||
|
||
@item @kbd{C-c C-x C-s} or short @kbd{$} (@code{org-agenda-archive})
|
||
@kindex C-c C-x C-s
|
||
@kindex $
|
||
@findex 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.
|
||
|
||
@item @kbd{T} (@code{org-agenda-show-tags})
|
||
@kindex T
|
||
@findex org-agenda-show-tags
|
||
@vindex org-agenda-show-inherited-tags
|
||
Show all tags associated with the current item. This is useful
|
||
if you have turned off @code{org-agenda-show-inherited-tags}, but
|
||
still want to see all tags of a headline occasionally.
|
||
|
||
@item @kbd{:} (@code{org-agenda-set-tags})
|
||
@kindex :
|
||
@findex 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.
|
||
|
||
@item @kbd{,} (@code{org-agenda-priority})
|
||
@kindex ,
|
||
@findex org-agenda-priority
|
||
Set the priority for the current item. Org mode prompts for the
|
||
priority character. If you reply with @kbd{@key{SPC}}, the
|
||
priority cookie is removed from the entry.
|
||
|
||
@item @kbd{P} (@code{org-agenda-show-priority})
|
||
@kindex P
|
||
@findex org-agenda-show-priority
|
||
Display weighted priority of current item.
|
||
|
||
@item @kbd{+} or @kbd{S-@key{UP}} (@code{org-agenda-priority-up})
|
||
@kindex +
|
||
@kindex S-UP
|
||
@findex 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 @kbd{r} key for this.
|
||
|
||
@item @kbd{-} or @kbd{S-@key{DOWN}} (@code{org-agenda-priority-down})
|
||
@kindex -
|
||
@kindex S-DOWN
|
||
@findex org-agenda-priority-down
|
||
Decrease the priority of the current item.
|
||
|
||
@item @kbd{C-c C-z} or short @kbd{z} (@code{org-agenda-add-note})
|
||
@kindex z
|
||
@kindex C-c C-z
|
||
@findex org-agenda-add-note
|
||
@vindex org-log-into-drawer
|
||
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 @code{org-log-into-drawer}, this may be inside a drawer.
|
||
|
||
@item @kbd{C-c C-a} (@code{org-attach})
|
||
@kindex C-c C-a
|
||
@findex org-attach
|
||
Dispatcher for all command related to attachments.
|
||
|
||
@item @kbd{C-c C-s} (@code{org-agenda-schedule})
|
||
@kindex C-c C-s
|
||
@findex org-agenda-schedule
|
||
Schedule this item. With a prefix argument, remove the
|
||
scheduling timestamp
|
||
|
||
@item @kbd{C-c C-d} (@code{org-agenda-deadline})
|
||
@kindex C-c C-d
|
||
@findex org-agenda-deadline
|
||
Set a deadline for this item. With a prefix argument, remove the
|
||
deadline.
|
||
|
||
@item @kbd{S-@key{RIGHT}} (@code{org-agenda-do-date-later})
|
||
@kindex S-RIGHT
|
||
@findex 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, @kbd{3 6 5 S-@key{RIGHT}} changes it by a year. With a @kbd{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 @kbd{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 @kbd{r} or @kbd{g} to update the buffer.
|
||
|
||
@item @kbd{S-@key{LEFT}} (@code{org-agenda-do-date-earlier})
|
||
@kindex S-LEFT
|
||
@findex org-agenda-do-date-earlier
|
||
Change the timestamp associated with the current line by one day
|
||
into the past.
|
||
|
||
@item @kbd{>} (@code{org-agenda-date-prompt})
|
||
@kindex >
|
||
@findex org-agenda-date-prompt
|
||
Change the timestamp associated with the current line. The key
|
||
@kbd{>} has been chosen, because it is the same as
|
||
@kbd{S-.} on my keyboard.
|
||
|
||
@item @kbd{I} (@code{org-agenda-clock-in})
|
||
@kindex I
|
||
@findex org-agenda-clock-in
|
||
Start the clock on the current item. If a clock is running
|
||
already, it is stopped first.
|
||
|
||
@item @kbd{O} (@code{org-agenda-clock-out})
|
||
@kindex O
|
||
@findex org-agenda-clock-out
|
||
Stop the previously started clock.
|
||
|
||
@item @kbd{X} (@code{org-agenda-clock-cancel})
|
||
@kindex X
|
||
@findex org-agenda-clock-cancel
|
||
Cancel the currently running clock.
|
||
|
||
@item @kbd{J} (@code{org-agenda-clock-goto})
|
||
@kindex J
|
||
@findex org-agenda-clock-goto
|
||
Jump to the running clock in another window.
|
||
|
||
@item @kbd{k} (@code{org-agenda-capture})
|
||
@kindex k
|
||
@findex org-agenda-capture
|
||
@cindex capturing, from agenda
|
||
@vindex org-capture-use-agenda-date
|
||
Like @code{org-capture}, but use the date at point as the default date
|
||
for the capture template. See @code{org-capture-use-agenda-date} to
|
||
make this the default behavior of @code{org-capture}.
|
||
@end table
|
||
|
||
@anchor{Bulk remote editing selected entries}
|
||
@subheading Bulk remote editing selected entries
|
||
|
||
@cindex remote editing, bulk, from agenda
|
||
@vindex org-agenda-bulk-custom-functions
|
||
|
||
@table @asis
|
||
@item @kbd{m} (@code{org-agenda-bulk-mark})
|
||
@kindex m
|
||
@findex 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.
|
||
|
||
@item @kbd{*} (@code{org-agenda-bulk-mark-all})
|
||
@kindex *
|
||
@findex org-agenda-bulk-mark-all
|
||
|
||
Mark all visible agenda entries for bulk action.
|
||
|
||
@item @kbd{u} (@code{org-agenda-bulk-unmark})
|
||
@kindex u
|
||
@findex org-agenda-bulk-unmark
|
||
|
||
Unmark entry for bulk action.
|
||
|
||
@item @kbd{U} (@code{org-agenda-bulk-remove-all-marks})
|
||
@kindex U
|
||
@findex org-agenda-bulk-remove-all-marks
|
||
|
||
Unmark all marked entries for bulk action.
|
||
|
||
@item @kbd{M-m} (@code{org-agenda-bulk-toggle})
|
||
@kindex M-m
|
||
@findex org-agenda-bulk-toggle
|
||
|
||
Toggle mark of the entry at point for bulk action.
|
||
|
||
@item @kbd{M-*} (@code{org-agenda-bulk-toggle-all})
|
||
@kindex M-*
|
||
@findex org-agenda-bulk-toggle-all
|
||
|
||
Mark entries matching a regular expression for bulk action.
|
||
|
||
@item @kbd{%} (@code{org-agenda-bulk-mark-regexp})
|
||
@kindex %
|
||
@findex org-agenda-bulk-mark-regexp
|
||
|
||
Mark entries matching a regular expression for bulk action.
|
||
|
||
@item @kbd{B} (@code{org-agenda-bulk-action})
|
||
@kindex B
|
||
@findex org-agenda-bulk-action
|
||
@vindex org-agenda-bulk-persistent-marks
|
||
|
||
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 @kbd{B} is passed through to the
|
||
@kbd{s} and @kbd{d} commands, to bulk-remove these
|
||
special timestamps. By default, marks are removed after the
|
||
bulk. If you want them to persist, set
|
||
@code{org-agenda-bulk-persistent-marks} to @code{t} or hit @kbd{p} at
|
||
the prompt.
|
||
|
||
@table @asis
|
||
@item @kbd{*}
|
||
Toggle persistent marks.
|
||
|
||
@item @kbd{$}
|
||
Archive all selected entries.
|
||
|
||
@item @kbd{A}
|
||
Archive entries by moving them to their respective archive
|
||
siblings.
|
||
|
||
@item @kbd{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.
|
||
|
||
@item @kbd{+}
|
||
Add a tag to all selected entries.
|
||
|
||
@item @kbd{-}
|
||
Remove a tag from all selected entries.
|
||
|
||
@item @kbd{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 @samp{++8d} or @samp{++2w}.
|
||
|
||
@item @kbd{d}
|
||
Set deadline to a specific date.
|
||
|
||
@item @kbd{r}
|
||
Prompt for a single refile target and move all entries. The
|
||
entries are no longer in the agenda; refresh (@kbd{g}) to
|
||
bring them back.
|
||
|
||
@item @kbd{S}
|
||
Reschedule randomly into the coming N days. N is prompted for.
|
||
With a prefix argument (@kbd{C-u B S}), scatter only
|
||
across weekdays.
|
||
|
||
@item @kbd{f}
|
||
@vindex org-agenda-bulk-custom-functions
|
||
Apply a function@footnote{You can also create persistent custom functions through
|
||
@code{org-agenda-bulk-custom-functions}.} to marked entries. For example, the
|
||
function below sets the @samp{CATEGORY} property of the entries to
|
||
@samp{web}.
|
||
|
||
@lisp
|
||
(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"))))
|
||
@end lisp
|
||
@end table
|
||
@end table
|
||
|
||
@anchor{Calendar commands}
|
||
@subheading Calendar commands
|
||
|
||
@cindex calendar commands, from agenda
|
||
|
||
@table @asis
|
||
@item @kbd{c} (@code{org-agenda-goto-calendar})
|
||
@kindex c
|
||
@findex org-agenda-goto-calendar
|
||
Open the Emacs calendar and move to the date at the agenda
|
||
cursor.
|
||
|
||
@item @kbd{c} (@code{org-calendar-goto-agenda})
|
||
@kindex c
|
||
@findex org-calendar-goto-agenda
|
||
When in the calendar, compute and show the Org agenda for the
|
||
date at the cursor.
|
||
|
||
@item @kbd{i} (@code{org-agenda-diary-entry})
|
||
@kindex i
|
||
@findex org-agenda-diary-entry
|
||
|
||
@cindex diary entries, creating from agenda
|
||
Insert a new entry into the diary, using the date at the cursor
|
||
and (for block entries) the date at the mark. This adds to the
|
||
Emacs diary file@footnote{This file is parsed for the agenda when
|
||
@code{org-agenda-include-diary} is set.}, in a way similar to the @kbd{i}
|
||
command in the calendar. The diary file pops up in another
|
||
window, where you can add the entry.
|
||
|
||
@vindex org-agenda-diary-file
|
||
If you configure @code{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 @samp{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
|
||
@code{org-agenda-diary-file} without further interaction. If you
|
||
directly press @kbd{@key{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 @kbd{k r} command.
|
||
|
||
@item @kbd{M} (@code{org-agenda-phases-of-moon})
|
||
@kindex M
|
||
@findex org-agenda-phases-of-moon
|
||
Show the phases of the moon for the three months around current
|
||
date.
|
||
|
||
@item @kbd{S} (@code{org-agenda-sunrise-sunset})
|
||
@kindex S
|
||
@findex 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.
|
||
|
||
@item @kbd{C} (@code{org-agenda-convert-date})
|
||
@kindex C
|
||
@findex org-agenda-convert-date
|
||
Convert the date at cursor into many other cultural and historic
|
||
calendars.
|
||
|
||
@item @kbd{H} (@code{org-agenda-holidays})
|
||
@kindex H
|
||
@findex org-agenda-holidays
|
||
Show holidays for three months around the cursor date.
|
||
@end table
|
||
|
||
@anchor{Quit and exit}
|
||
@subheading Quit and exit
|
||
|
||
@table @asis
|
||
@item @kbd{q} (@code{org-agenda-quit})
|
||
@kindex q
|
||
@findex org-agenda-quit
|
||
|
||
Quit agenda, remove the agenda buffer.
|
||
|
||
@item @kbd{x} (@code{org-agenda-exit})
|
||
@kindex x
|
||
@findex org-agenda-exit
|
||
|
||
@cindex agenda files, removing buffers
|
||
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.
|
||
@end table
|
||
|
||
@node Custom Agenda Views
|
||
@section Custom Agenda Views
|
||
|
||
@cindex custom agenda views
|
||
@cindex agenda views, custom
|
||
|
||
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 @ref{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.
|
||
@end menu
|
||
|
||
@node Storing searches
|
||
@subsection 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).
|
||
|
||
@kindex C @r{(Agenda dispatcher)}
|
||
@vindex org-agenda-custom-commands
|
||
@cindex agenda views, main example
|
||
@cindex agenda, as an agenda views
|
||
@cindex agenda*, as an agenda views
|
||
@cindex tags, as an agenda view
|
||
@cindex todo, as an agenda view
|
||
@cindex tags-todo
|
||
@cindex todo-tree
|
||
@cindex occur-tree
|
||
@cindex tags-tree
|
||
Custom commands are configured in the variable
|
||
@code{org-agenda-custom-commands}. You can customize this variable, for
|
||
example by pressing @kbd{C} from the agenda dispatcher (see @ref{Agenda Dispatcher}). You can also directly set it with Emacs Lisp in
|
||
the Emacs init file. The following example contains all valid agenda
|
||
views:
|
||
|
||
@lisp
|
||
(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")))
|
||
@end lisp
|
||
|
||
@noindent
|
||
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 will be 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@footnote{You can provide a description for a prefix key by inserting
|
||
a cons cell with the prefix and the description.}. 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:
|
||
|
||
@table @asis
|
||
@item @kbd{x}
|
||
as a global search for agenda entries planned@footnote{@emph{Planned} means here that these entries have some planning
|
||
information attached to them, like a time-stamp, a scheduled or
|
||
a deadline string. See @code{org-agenda-entry-types} on how to set what
|
||
planning information is taken into account.} this
|
||
week/day.
|
||
|
||
@item @kbd{y}
|
||
as the same search, but only for entries with an hour
|
||
specification like @samp{[h]h:mm}---think of them as appointments.
|
||
|
||
@item @kbd{w}
|
||
as a global search for TODO entries with @samp{WAITING} as the TODO
|
||
keyword.
|
||
|
||
@item @kbd{W}
|
||
as the same search, but only in the current buffer and displaying
|
||
the results as a sparse tree.
|
||
|
||
@item @kbd{u}
|
||
as a global tags search for headlines tagged @samp{boss} but not
|
||
@samp{urgent}.
|
||
|
||
@item @kbd{v}
|
||
The same search, but limiting it to headlines that are also TODO
|
||
items.
|
||
|
||
@item @kbd{U}
|
||
as the same search, but only in the current buffer and displaying
|
||
the result as a sparse tree.
|
||
|
||
@item @kbd{f}
|
||
to create a sparse tree (again, current buffer only) with all
|
||
entries containing the word @samp{FIXME}.
|
||
|
||
@item @kbd{h}
|
||
as a prefix command for a @samp{HOME} tags search where you have to
|
||
press an additional key (@kbd{l}, @kbd{p} or
|
||
@kbd{k}) to select a name (Lisa, Peter, or Kim) as
|
||
additional tag to match.
|
||
@end table
|
||
|
||
Note that @code{*-tree} agenda views need to be called from an Org buffer
|
||
as they operate on the current buffer only.
|
||
|
||
@node Block agenda
|
||
@subsection Block agenda
|
||
|
||
@cindex block agenda
|
||
@cindex agenda, with block views
|
||
|
||
Another possibility is the construction of agenda views that comprise
|
||
the results of @emph{several} commands, each of which creates a block in
|
||
the agenda buffer. The available commands include @code{agenda} for the
|
||
daily or weekly agenda (as created with @kbd{a}) , @code{alltodo} for
|
||
the global TODO list (as constructed with @kbd{t}), and the
|
||
matching commands discussed above: @code{todo}, @code{tags}, and @code{tags-todo}.
|
||
Here are two examples:
|
||
|
||
@lisp
|
||
(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")))))
|
||
@end lisp
|
||
|
||
@noindent
|
||
This defines @kbd{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 @samp{home},
|
||
and also all lines tagged with @samp{garden}. Finally the command
|
||
@kbd{o} provides a similar view for office tasks.
|
||
|
||
@node Setting options
|
||
@subsection Setting options for custom commands
|
||
|
||
@cindex options, for custom agenda views
|
||
|
||
@vindex org-agenda-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 @code{org-agenda-custom-commands}. For example:
|
||
|
||
@lisp
|
||
(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)))))
|
||
@end lisp
|
||
|
||
@noindent
|
||
Now the @kbd{w} command sorts the collected entries only by
|
||
priority, and the prefix format is modified to just say @samp{Mixed:}
|
||
instead of giving the category of the entry. The sparse tags tree of
|
||
@kbd{U} now turns out ultra-compact, because neither the headline
|
||
hierarchy above the match, nor the headline following the match are
|
||
shown. The command @kbd{N} does a text search limited to only
|
||
a single file.
|
||
|
||
For command sets creating a block agenda, @code{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 @ref{Block agenda}), let's change the sorting strategy for the @kbd{h}
|
||
commands to @code{priority-down}, but let's sort the results for GARDEN
|
||
tags query in the opposite order, @code{priority-up}. This would look like
|
||
this:
|
||
|
||
@lisp
|
||
(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")))))
|
||
@end lisp
|
||
|
||
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 @emph{values} are just Lisp expressions. So if the
|
||
value is a string, you need to add the double-quotes around the value
|
||
yourself.
|
||
|
||
@vindex org-agenda-custom-commands-contexts
|
||
To control whether an agenda command should be accessible from
|
||
a specific context, you can customize
|
||
@code{org-agenda-custom-commands-contexts}. Let's say for example that you
|
||
have an agenda command @kbd{o} displaying a view that you only
|
||
need when reading emails. Then you would configure this option like
|
||
this:
|
||
|
||
@lisp
|
||
(setq org-agenda-custom-commands-contexts
|
||
'(("o" (in-mode . "message-mode"))))
|
||
@end lisp
|
||
|
||
You can also tell that the command key @kbd{o} should refer to
|
||
another command key @kbd{r}. In that case, add this command key
|
||
like this:
|
||
|
||
@lisp
|
||
(setq org-agenda-custom-commands-contexts
|
||
'(("o" "r" (in-mode . "message-mode"))))
|
||
@end lisp
|
||
|
||
See the docstring of the variable for more information.
|
||
|
||
@node Exporting Agenda Views
|
||
@section Exporting Agenda Views
|
||
|
||
@cindex agenda views, exporting
|
||
|
||
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@footnote{For HTML you need to install Hrvoje Niksic's @samp{htmlize.el}
|
||
from @uref{https://github.com/hniksic/emacs-htmlize, Hrvoje Niksic's repository}.}, Postscript,
|
||
PDF@footnote{To create PDF output, the Ghostscript ps2pdf utility must be
|
||
installed on the system. Selecting a PDF file also creates the
|
||
postscript file.}, and iCalendar files. If you want to do this only
|
||
occasionally, use the following command:
|
||
|
||
@table @asis
|
||
@item @kbd{C-x C-w} (@code{org-agenda-write})
|
||
@kindex C-x C-w
|
||
@findex org-agenda-write
|
||
@cindex exporting agenda views
|
||
@cindex agenda views, exporting
|
||
|
||
@vindex org-agenda-exporter-settings
|
||
Write the agenda view to a file.
|
||
@end table
|
||
|
||
If you need to export certain agenda views frequently, you can
|
||
associate any custom agenda command with a list of output file
|
||
names@footnote{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.}. 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.
|
||
|
||
@lisp
|
||
(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"))))
|
||
@end lisp
|
||
|
||
The extension of the file name determines the type of export. If it
|
||
is @samp{.html}, Org mode uses the htmlize package to convert the buffer to
|
||
HTML and save it to this file name. If the extension is @samp{.ps},
|
||
@code{ps-print-buffer-with-faces} is used to produce Postscript output. If
|
||
the extension is @samp{.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 @emph{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 @emph{all} specified
|
||
files in one step:
|
||
|
||
@table @asis
|
||
@item @kbd{e} (@code{org-store-agenda-views})
|
||
@kindex e @r{(Agenda dispatcher)}
|
||
@findex org-store-agenda-views
|
||
Export all agenda views that have export file names associated
|
||
with them.
|
||
@end table
|
||
|
||
You can use the options section of the custom agenda commands to also
|
||
set options for the export commands. For example:
|
||
|
||
@lisp
|
||
(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"))))
|
||
@end lisp
|
||
|
||
@noindent
|
||
@vindex org-agenda-exporter-settings
|
||
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
|
||
@code{org-agenda-exporter-settings} also apply, e.g.,
|
||
|
||
@lisp
|
||
(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)))
|
||
@end lisp
|
||
|
||
@noindent
|
||
but the settings in @code{org-agenda-custom-commands} take precedence.
|
||
|
||
@noindent
|
||
From the command line you may also use:
|
||
|
||
@example
|
||
emacs -eval (org-batch-store-agenda-views) -kill
|
||
@end example
|
||
|
||
@noindent
|
||
or, if you need to modify some parameters@footnote{Quoting depends on the system you use, please check the FAQ
|
||
for examples.}
|
||
|
||
@example
|
||
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
|
||
@end example
|
||
|
||
@noindent
|
||
which creates the agenda views restricted to the file
|
||
@samp{~/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 @ref{Extracting Agenda Information}, for
|
||
more information.
|
||
|
||
@node Agenda Column View
|
||
@section Using Column View in the Agenda
|
||
|
||
@cindex column view, in agenda
|
||
@cindex agenda, column view
|
||
|
||
Column view (see @ref{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.
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-x C-c} (@code{org-agenda-columns})
|
||
@kindex C-c C-x C-c
|
||
@findex org-agenda-columns
|
||
|
||
Turn on column view in the agenda.
|
||
@end table
|
||
|
||
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:
|
||
|
||
@enumerate
|
||
@item
|
||
@vindex org-columns-default-format
|
||
@vindex org-overriding-columns-format
|
||
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 the variable
|
||
@code{org-agenda-overriding-columns-format} is currently set, and if so,
|
||
takes the format from there. Otherwise it takes the format
|
||
associated with the first item in the agenda, or, if that item does
|
||
not have a specific format (defined in a property, or in its file),
|
||
it uses @code{org-columns-default-format}.
|
||
|
||
@item
|
||
@cindex @samp{CLOCKSUM}, special property
|
||
If any of the columns has a summary type defined (see @ref{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
|
||
@samp{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
|
||
@emph{twice}---for example as scheduled and as a deadline---and it may
|
||
show two entries from the same hierarchy (for example a @emph{parent}
|
||
and its @emph{child}). In these cases, the summation in the agenda
|
||
leads to incorrect results because some values count double.
|
||
|
||
@item
|
||
When the column view in the agenda shows the @samp{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 @kbd{R} in the agenda).
|
||
|
||
@item
|
||
@cindex @samp{CLOCKSUM_T}, special property
|
||
When the column view in the agenda shows the @samp{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 @samp{CLOCKSUM}---and with
|
||
the planned total effort for it.
|
||
@end enumerate
|
||
|
||
@node Markup
|
||
@chapter Markup for Rich Export
|
||
|
||
When exporting Org documents, the exporter tries to reflect the
|
||
structure of the document as accurately as possible in the back-end.
|
||
Since export targets like HTML and @LaTeX{} allow much richer formatting,
|
||
Org mode has rules on how to prepare text for rich export. This
|
||
section summarizes the markup rules used in an Org mode buffer.
|
||
|
||
@menu
|
||
* Paragraphs:: The basic unit of text.
|
||
* Emphasis and Monospace:: Bold, italic, etc.
|
||
* Horizontal Rules:: Make a line.
|
||
* Images and Tables:: Images, tables and caption mechanism.
|
||
* Literal Examples:: Source code examples with special formatting.
|
||
* Special Symbols:: Greek letters and other symbols.
|
||
* Subscripts and Superscripts:: Simple syntax for raising/lowering text.
|
||
* Embedded @LaTeX{}:: LaTeX can be freely used inside Org documents.
|
||
@end menu
|
||
|
||
@node Paragraphs
|
||
@section Paragraphs
|
||
|
||
@cindex paragraphs, markup rules
|
||
|
||
Paragraphs are separated by at least one empty line. If you need to
|
||
enforce a line break within a paragraph, use @code{\\} 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.
|
||
|
||
@cindex @samp{BEGIN_VERSE}
|
||
@cindex verse blocks
|
||
@example
|
||
#+BEGIN_VERSE
|
||
Great clouds overhead
|
||
Tiny black birds rise and fall
|
||
Snow covers Emacs
|
||
|
||
---AlexSchroeder
|
||
#+END_VERSE
|
||
@end example
|
||
|
||
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:
|
||
|
||
@cindex @samp{BEGIN_QUOTE}
|
||
@cindex quote blocks
|
||
@example
|
||
#+BEGIN_QUOTE
|
||
Everything should be made as simple as possible,
|
||
but not any simpler ---Albert Einstein
|
||
#+END_QUOTE
|
||
@end example
|
||
|
||
If you would like to center some text, do it like this:
|
||
|
||
@cindex @samp{BEGIN_CENTER}
|
||
@cindex center blocks
|
||
@example
|
||
#+BEGIN_CENTER
|
||
Everything should be made as simple as possible, \\
|
||
but not any simpler
|
||
#+END_CENTER
|
||
@end example
|
||
|
||
@node Emphasis and Monospace
|
||
@section Emphasis and Monospace
|
||
|
||
@cindex underlined text, markup rules
|
||
@cindex bold text, markup rules
|
||
@cindex italic text, markup rules
|
||
@cindex verbatim text, markup rules
|
||
@cindex code text, markup rules
|
||
@cindex strike-through text, markup rules
|
||
|
||
You can make words @samp{*bold*}, @samp{/italic/}, @samp{_underlined_}, @samp{=verbatim=}
|
||
and @samp{~code~}, and, if you must, @samp{+strike-through+}. Text in the code
|
||
and verbatim string is not processed for Org mode specific syntax; it
|
||
is exported verbatim.
|
||
|
||
@vindex org-fontify-emphasized-text
|
||
To turn off fontification for marked up text, you can set
|
||
@code{org-fontify-emphasized-text} to @code{nil}. To narrow down the list of
|
||
available markup syntax, you can customize @code{org-emphasis-alist}.
|
||
|
||
@node Horizontal Rules
|
||
@section Horizontal Rules
|
||
|
||
@cindex horizontal rules, markup rules
|
||
|
||
A line consisting of only dashes, and at least 5 of them, is exported
|
||
as a horizontal line.
|
||
|
||
@node Images and Tables
|
||
@section Images and Tables
|
||
|
||
@cindex tables, markup rules
|
||
@cindex @samp{CAPTION}, keyword
|
||
@cindex @samp{NAME}, keyword
|
||
|
||
Both the native Org mode tables (see @ref{Tables}) and tables formatted
|
||
with the @samp{table.el} package are exported properly. For Org mode
|
||
tables, the lines before the first horizontal separator line become
|
||
table header lines. You can use the following lines somewhere before
|
||
the table to assign a caption and a label for cross references, and in
|
||
the text you can refer to the object with @samp{[[tab:basic-data]]} (see
|
||
@ref{Internal Links}):
|
||
|
||
@example
|
||
#+CAPTION: This is the caption for the next table (or link)
|
||
#+NAME: tab:basic-data
|
||
| ... | ... |
|
||
|-----+-----|
|
||
@end example
|
||
|
||
Optionally, the caption can take the form:
|
||
|
||
@example
|
||
#+CAPTION[Caption for list of tables]: Caption for table.
|
||
@end example
|
||
|
||
@cindex inlined images, markup rules
|
||
Some back-ends allow you to directly include images into the exported
|
||
document. Org does this, if a link to an image file does not have
|
||
a description part, for example @samp{[[./img/a.jpg]]}. If you wish to define
|
||
a caption for the image and maybe a label for internal cross
|
||
references, make sure that the link is on a line by itself and precede
|
||
it with @samp{CAPTION} and @samp{NAME} keywords as follows:
|
||
|
||
@example
|
||
#+CAPTION: This is the caption for the next figure link (or table)
|
||
#+NAME: fig:SED-HR4049
|
||
[[./img/a.jpg]]
|
||
@end example
|
||
|
||
@noindent
|
||
Such images can be displayed within the buffer. See @ref{Handling Links, , the discussion of
|
||
image links}.
|
||
|
||
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.
|
||
|
||
@node Literal Examples
|
||
@section Literal Examples
|
||
|
||
@cindex literal examples, markup
|
||
@cindex code line references, markup
|
||
|
||
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.
|
||
|
||
@cindex @samp{BEGIN_EXAMPLE}
|
||
@cindex example block
|
||
@example
|
||
#+BEGIN_EXAMPLE
|
||
Some example from a text file.
|
||
#+END_EXAMPLE
|
||
@end example
|
||
|
||
Note that such blocks may be @emph{indented} in order to align nicely with
|
||
indented text and in particular with plain list structure (see
|
||
@ref{Plain Lists}). 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:
|
||
|
||
@example
|
||
Here is an example
|
||
: Some example from a text file.
|
||
@end example
|
||
|
||
@cindex formatting source code, markup rules
|
||
@vindex org-latex-listings
|
||
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@footnote{This works automatically for the HTML backend (it requires
|
||
version 1.34 of the @samp{htmlize.el} package, which you need to install).
|
||
Fontified code chunks in @LaTeX{} can be achieved using either the
|
||
listings package or the @uref{https://github.com/gpoore/minted, minted} package. Refer to
|
||
@code{org-export-latex-listings} for details.}. 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@footnote{Source code in code blocks may also be evaluated either
|
||
interactively or on export. See @ref{Working with Source Code} for more
|
||
information on evaluating code blocks.},
|
||
see @ref{Structure Templates} for shortcuts to easily insert code blocks.
|
||
|
||
@cindex @samp{BEGIN_SRC}
|
||
@cindex src block
|
||
@example
|
||
#+BEGIN_SRC emacs-lisp
|
||
(defun org-xor (a b)
|
||
"Exclusive or."
|
||
(if a (not b) b))
|
||
#+END_SRC
|
||
@end example
|
||
|
||
Both in @samp{example} and in @samp{src} snippets, you can add a @samp{-n} switch to
|
||
the end of the @samp{#+BEGIN} line, to get the lines of the example
|
||
numbered. The @samp{-n} takes an optional numeric argument specifying the
|
||
starting line number of the block. If you use a @samp{+n} switch, the
|
||
numbering from the previous numbered snippet is continued in the
|
||
current one. The @samp{+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.
|
||
|
||
@example
|
||
#+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
|
||
@end example
|
||
|
||
In literal examples, Org interprets strings like @samp{(ref:name)} as
|
||
labels, and use them as targets for special hyperlinks like
|
||
@samp{[[(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 @samp{-r} switch which @emph{removes} the labels from the
|
||
source code@footnote{Adding @samp{-k} to @samp{-n -r} @emph{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.}. With the @samp{-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:
|
||
|
||
@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.
|
||
@end example
|
||
|
||
@cindex indentation, in source blocks
|
||
Finally, you can use @samp{-i} to preserve the indentation of a specific
|
||
code block (see @ref{Editing Source Code}).
|
||
|
||
@vindex org-coderef-label-format
|
||
If the syntax for the label format conflicts with the language syntax,
|
||
use a @samp{-l} switch to change the format, for example
|
||
|
||
@example
|
||
#+BEGIN_SRC pascal -n -r -l "((%s))"
|
||
@end example
|
||
|
||
@noindent
|
||
See also the variable @code{org-coderef-label-format}.
|
||
|
||
HTML export also allows examples to be published as text areas (see
|
||
@ref{Text areas in HTML export}).
|
||
|
||
Because the @samp{#+BEGIN} @dots{} @samp{#+END} patterns need to be added so often,
|
||
a shortcut is provided (see @ref{Structure Templates}).
|
||
|
||
@table @asis
|
||
@item @kbd{C-c '} (@code{org-edit-special})
|
||
@kindex C-c '
|
||
@findex 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 @kbd{C-c '} again@footnote{Upon exit, lines starting with @samp{*}, @samp{,*}, @samp{#+} and @samp{,#+} get
|
||
a comma prepended, to keep them from being interpreted by Org as
|
||
outline nodes or special syntax. These commas are stripped when
|
||
editing with @kbd{C-c '}, and also before export.}. 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 @code{artist-mode}@footnote{You may select a different-mode with the variable
|
||
@code{org-edit-fixed-width-region-mode}.} to
|
||
allow creating ASCII drawings easily. Using this command in an
|
||
empty line creates a new fixed-width region.
|
||
@end table
|
||
|
||
@cindex storing link, in a source code buffer
|
||
Calling @code{org-store-link} (see @ref{Handling Links}) while editing a source
|
||
code example in a temporary buffer created with @kbd{C-c '}
|
||
prompts for a label. Make sure that it is unique in the current
|
||
buffer, and insert it with the proper formatting like @samp{(ref:label)} at
|
||
the end of the current line. Then the label is stored as a link
|
||
@samp{(label)}, for retrieval with @kbd{C-c C-l}.
|
||
|
||
@node Special Symbols
|
||
@section Special Symbols
|
||
|
||
@cindex math symbols
|
||
@cindex special symbols
|
||
@cindex @TeX{} macros
|
||
@cindex @LaTeX{} fragments, markup rules
|
||
@cindex HTML entities
|
||
@cindex @LaTeX{} entities
|
||
|
||
You can use @LaTeX{}-like syntax to insert special symbols---named
|
||
entities---like @samp{\alpha} to indicate the Greek letter, or @samp{\to} to indicate
|
||
an arrow. Completion for these symbols is available, just type @samp{\}
|
||
and maybe a few letters, and press @kbd{M-@key{TAB}} to see possible
|
||
completions. If you need such a symbol inside a word, terminate it
|
||
with a pair of curly brackets. For example
|
||
|
||
@example
|
||
Pro tip: Given a circle \Gamma of diameter d, the length of its
|
||
circumference is \pi@{@}d.
|
||
@end example
|
||
|
||
@findex org-entities-help
|
||
@vindex org-entities-user
|
||
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 @code{org-entities-help}. It is also
|
||
possible to provide your own special symbols in the variable
|
||
@code{org-entities-user}.
|
||
|
||
During export, these symbols are transformed into the native format of
|
||
the exporter back-end. Strings like @samp{\alpha} are exported as @samp{α} in
|
||
the HTML output, and as @samp{\(\alpha\)} in the @LaTeX{} output. Similarly, @samp{\nbsp}
|
||
becomes @samp{ } in HTML and @samp{~} in @LaTeX{}.
|
||
|
||
@cindex escaping characters
|
||
Entities may also be used as a way to escape markup in an Org
|
||
document, e.g., @samp{\under@{@}not underlined\under} exports as @samp{_not underlined_}.
|
||
|
||
@cindex special symbols, in-buffer display
|
||
If you would like to see entities displayed as UTF-8 characters, use
|
||
the following command@footnote{You can turn this on by default by setting the variable
|
||
@code{org-pretty-entities}, or on a per-file base with the @samp{STARTUP} option
|
||
@samp{entitiespretty}.}:
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-x \} (@code{org-toggle-pretty-entities})
|
||
@kindex C-c C-x \
|
||
@findex 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.
|
||
@end table
|
||
|
||
@cindex shy hyphen, special symbol
|
||
@cindex dash, special symbol
|
||
@cindex ellipsis, special symbol
|
||
In addition to regular entities defined above, Org exports in
|
||
a special way@footnote{This behavior can be disabled with @samp{-} export setting (see
|
||
@ref{Export Settings}).} the following commonly used character
|
||
combinations: @samp{\-} is treated as a shy hyphen, @samp{--} and @samp{---} are
|
||
converted into dashes, and @samp{...} becomes a compact set of dots.
|
||
|
||
@node Subscripts and Superscripts
|
||
@section Subscripts and Superscripts
|
||
|
||
@cindex subscript
|
||
@cindex superscript
|
||
|
||
@samp{^} and @samp{_} 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
|
||
|
||
@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@}.
|
||
@end example
|
||
|
||
@vindex org-use-sub-superscripts
|
||
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 @code{org-use-sub-superscripts} to
|
||
change this convention. For example, when setting this variable to
|
||
@code{@{@}}, @samp{a_b} is not interpreted as a subscript, but @samp{a_@{b@}} is.
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-x \} (@code{org-toggle-pretty-entities~})
|
||
@kindex C-c C-x \
|
||
@findex org-toggle-pretty-entities
|
||
|
||
In addition to showing entities as UTF-8 characters, this command
|
||
also formats sub- and superscripts in a WYSIWYM way.
|
||
@end table
|
||
|
||
@node Embedded @LaTeX{}
|
||
@section Embedded @LaTeX{}
|
||
|
||
@cindex @TeX{} interpretation
|
||
@cindex @LaTeX{} interpretation
|
||
|
||
Plain ASCII is normally sufficient for almost all note taking.
|
||
Exceptions include scientific notes, which often require mathematical
|
||
symbols and the occasional formula. @LaTeX{}@footnote{@LaTeX{} is a macro system based on Donald@tie{}E.@tie{}Knuth's @TeX{}
|
||
system. Many of the features described here as ``@LaTeX{}'' are really
|
||
from @TeX{}, but for simplicity I am blurring this distinction.} 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?
|
||
* CD@LaTeX{} mode:: Speed up entering of formulas.
|
||
@end menu
|
||
|
||
@node @LaTeX{} fragments
|
||
@subsection @LaTeX{} fragments
|
||
|
||
@cindex @LaTeX{} fragments
|
||
|
||
@vindex org-format-latex-header
|
||
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
|
||
@uref{http://www.mathjax.org, MathJax} (see @ref{Math formatting in HTML export}) or transcode the math
|
||
into images (see @ref{Previewing @LaTeX{} fragments}).
|
||
|
||
@LaTeX{} fragments do not need any special marking at all. The following
|
||
snippets are identified as @LaTeX{} source code:
|
||
|
||
@itemize
|
||
@item
|
||
Environments of any kind@footnote{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.}. The only requirement is that the
|
||
@samp{\begin} statement appears on a new line, preceded by only
|
||
whitespace.
|
||
|
||
@item
|
||
Text within the usual @LaTeX{} math delimiters. To avoid conflicts
|
||
with currency specifications, single @samp{$} characters are only
|
||
recognized as math delimiters if the enclosed text contains at most
|
||
two line breaks, is directly attached to the @samp{$} characters with no
|
||
whitespace in between, and if the closing @samp{$} is followed by
|
||
whitespace, punctuation or a dash. For the other delimiters, there
|
||
is no such restriction, so when in doubt, use @samp{\(...\)} as inline
|
||
math delimiters.
|
||
@end itemize
|
||
|
||
@noindent
|
||
For example:
|
||
|
||
@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@} \].
|
||
@end example
|
||
|
||
@vindex org-export-with-latex
|
||
@LaTeX{} processing can be configured with the variable
|
||
@code{org-export-with-latex}. The default setting is @code{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:
|
||
|
||
@multitable {aaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
|
||
@item @samp{#+OPTIONS: tex:t}
|
||
@tab Do the right thing automatically (MathJax)
|
||
@item @samp{#+OPTIONS: tex:nil}
|
||
@tab Do not process @LaTeX{} fragments at all
|
||
@item @samp{#+OPTIONS: tex:verbatim}
|
||
@tab Verbatim export, for jsMath or so
|
||
@end multitable
|
||
|
||
@node Previewing @LaTeX{} fragments
|
||
@subsection Previewing @LaTeX{} fragments
|
||
|
||
@cindex @LaTeX{} fragments, preview
|
||
|
||
@vindex org-preview-latex-default-process
|
||
If you have a working @LaTeX{} installation and @samp{dvipng}, @samp{dvisvgm} or
|
||
@samp{convert} installed@footnote{These are respectively available at
|
||
@uref{http://sourceforge.net/projects/dvipng/}, @uref{http://dvisvgm.bplaced.net/}
|
||
and from the ImageMagick suite. Choose the converter by setting the
|
||
variable @code{org-preview-latex-default-process} accordingly.}, @LaTeX{} fragments can be processed to
|
||
produce images of the typeset expressions to be used for inclusion
|
||
while exporting to HTML (see @ref{@LaTeX{} fragments}), or for inline
|
||
previewing within Org mode.
|
||
|
||
@vindex org-format-latex-options
|
||
@vindex org-format-latex-header
|
||
You can customize the variables @code{org-format-latex-options} and
|
||
@code{org-format-latex-header} to influence some aspects of the preview.
|
||
In particular, the @code{:scale} (and for HTML export, @code{:html-scale})
|
||
property of the former can be used to adjust the size of the preview
|
||
images.
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-x C-l} (@code{org-toggle-latex-fragment})
|
||
@kindex C-c C-x C-l
|
||
@findex org-toggle-latex-fragment
|
||
|
||
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 prefix argument, process the
|
||
entire subtree. When called with two prefix arguments, or when
|
||
the cursor is before the first headline, process the entire
|
||
buffer.
|
||
@end table
|
||
|
||
@vindex org-startup-with-latex-preview
|
||
You can turn on the previewing of all @LaTeX{} fragments in a file with
|
||
|
||
@example
|
||
#+STARTUP: latexpreview
|
||
@end example
|
||
|
||
To disable it, simply use
|
||
|
||
@example
|
||
#+STARTUP: nolatexpreview
|
||
@end example
|
||
|
||
@node CD@LaTeX{} mode
|
||
@subsection Using CD@LaTeX{} to enter math
|
||
|
||
@cindex CD@LaTeX{}
|
||
|
||
CD@LaTeX{} mode is a minor mode that is normally used in combination with
|
||
a major @LaTeX{} mode like AUC@TeX{} in order to speed-up insertion of
|
||
environments and math templates. Inside Org mode, you can make use of
|
||
some of the features of CD@LaTeX{} mode. You need to install
|
||
@samp{cdlatex.el} and @samp{texmathp.el} (the latter comes also with AUC@TeX{})
|
||
from @uref{http://www.astro.uva.nl/~dominik/Tools/cdlatex}. Do not use
|
||
CD@LaTeX{} mode itself under Org mode, but use the light version
|
||
@code{org-cdlatex-mode} that comes as part of Org mode. Turn it on for the
|
||
current buffer with @kbd{M-x org-cdlatex-mode}, or for all Org
|
||
files with
|
||
|
||
@lisp
|
||
(add-hook 'org-mode-hook 'turn-on-org-cdlatex)
|
||
@end lisp
|
||
|
||
When this mode is enabled, the following features are present (for
|
||
more details see the documentation of CD@LaTeX{} mode):
|
||
|
||
@table @asis
|
||
@item @kbd{C-c @{}
|
||
@kindex C-c @{
|
||
|
||
Insert an environment template.
|
||
|
||
@item @kbd{@key{TAB}}
|
||
@kindex TAB
|
||
|
||
The @kbd{@key{TAB}} key expands the template if the cursor is
|
||
inside a @LaTeX{} fragment@footnote{Org mode has a method to test if the cursor is inside such
|
||
a fragment, see the documentation of the function
|
||
@code{org-inside-LaTeX-fragment-p}.}. For example, @kbd{@key{TAB}}
|
||
expands @samp{fr} to @samp{\frac@{@}@{@}} and position the cursor correctly
|
||
inside the first brace. Another @kbd{@key{TAB}} gets you into the
|
||
second brace.
|
||
|
||
Even outside fragments, @kbd{@key{TAB}} expands environment
|
||
abbreviations at the beginning of a line. For example, if you
|
||
write @samp{equ} at the beginning of a line and press @kbd{@key{TAB}},
|
||
this abbreviation is expanded to an @samp{equation} environment. To
|
||
get a list of all abbreviations, type @kbd{M-x cdlatex-command-help}.
|
||
|
||
@item @kbd{^}
|
||
@itemx @kbd{_}
|
||
@kindex _
|
||
@kindex ^
|
||
@vindex cdlatex-simplify-sub-super-scripts
|
||
|
||
Pressing @kbd{_} and @kbd{^} inside a @LaTeX{} fragment
|
||
inserts these characters together with a pair of braces. If you
|
||
use @kbd{@key{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 @code{cdlatex-simplify-sub-super-scripts}).
|
||
|
||
@item @kbd{`}
|
||
@kindex `
|
||
|
||
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.
|
||
|
||
@item @kbd{'}
|
||
@kindex '
|
||
|
||
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.
|
||
@end table
|
||
|
||
@node Exporting
|
||
@chapter Exporting
|
||
|
||
@cindex exporting
|
||
|
||
Sometimes, you may want to pretty print your notes, publish them on
|
||
the web or even share them with people not using Org. In these cases,
|
||
the Org export facilities can be used to convert your documents to
|
||
a variety of other formats, while retaining as much structure (see
|
||
@ref{Document Structure}) and markup (see @ref{Markup}) as
|
||
possible.
|
||
|
||
@cindex export back-end
|
||
Libraries responsible for such translation are called back-ends. Org
|
||
ships with the following ones
|
||
|
||
@itemize
|
||
@item
|
||
@emph{ascii} (ASCII format)
|
||
@item
|
||
@emph{beamer} (@LaTeX{} Beamer format)
|
||
@item
|
||
@emph{html} (HTML format)
|
||
@item
|
||
@emph{icalendar} (iCalendar format)
|
||
@item
|
||
@emph{latex} (@LaTeX{} format)
|
||
@item
|
||
@emph{md} (Markdown format)
|
||
@item
|
||
@emph{odt} (OpenDocument Text format)
|
||
@item
|
||
@emph{org} (Org format)
|
||
@item
|
||
@emph{texinfo} (Texinfo format)
|
||
@item
|
||
@emph{man} (Man page format)
|
||
@end itemize
|
||
|
||
@noindent
|
||
Org also uses additional libraries located in @samp{contrib/} directory
|
||
(see @ref{Installation}). Users can install additional export libraries
|
||
for additional formats from the Emacs packaging system. For easy
|
||
discovery, these packages have a common naming scheme: @code{ox-NAME},
|
||
where @var{NAME} is one of the formats. For example,
|
||
@code{ox-koma-letter} @emph{koma-letter} back-end.
|
||
|
||
@vindex org-export-backends
|
||
Org loads back-ends for the following formats by default: ASCII, HTML,
|
||
iCalendar, @LaTeX{} and ODT. Org can load additional back-ends either of
|
||
two ways: through the @code{org-export-backends} variable configuration;
|
||
or, by requiring the library in the Emacs init file like this:
|
||
|
||
@lisp
|
||
(require 'ox-md)
|
||
@end lisp
|
||
|
||
@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::
|
||
* 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 Configuration:: Fine-tuning the export output.
|
||
* Export in Foreign Buffers:: Author tables and lists in Org syntax.
|
||
@end menu
|
||
|
||
@node The Export Dispatcher
|
||
@section The Export Dispatcher
|
||
|
||
@cindex dispatcher, for export commands
|
||
@cindex 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.
|
||
|
||
@vindex org-export-dispatch-use-expert-ui
|
||
Org also has a minimal prompt interface for the export dispatcher.
|
||
When the variable @code{org-export-dispatch-use-expert-ui} is set to
|
||
a non-@code{nil} value, Org prompts in the minibuffer. To switch back to
|
||
the hierarchical menu, press @kbd{?}.
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-e} (@code{org-export})
|
||
@kindex C-c C-e
|
||
@findex org-export
|
||
|
||
Invokes the export dispatcher interface. The options show
|
||
default settings. The @kbd{C-u} prefix argument preserves
|
||
options from the previous export, including any sub-tree
|
||
selections.
|
||
@end table
|
||
|
||
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.
|
||
|
||
@table @asis
|
||
@item @kbd{C-a}
|
||
@kindex C-c C-e 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 thereby
|
||
releasing the current interface. This is particularly useful
|
||
when exporting long documents.
|
||
|
||
Output from an asynchronous export is saved on the ``the export
|
||
stack''. To view this stack, call the export dispatcher with
|
||
a double @kbd{C-u} prefix argument. If already in the
|
||
export dispatcher menu, @kbd{&} displays the stack.
|
||
|
||
@vindex org-export-async-init-file
|
||
To make the background export process the default, customize the
|
||
variable, @code{org-export-in-background}. Additionally, you can set
|
||
the initialization file used by the background process with
|
||
@code{org-export-async-init-file}.
|
||
|
||
@vindex org-export-in-background
|
||
You can make asynchronous export the default by setting
|
||
@code{org-export-in-background}.
|
||
|
||
@item @kbd{C-b}
|
||
@kindex C-c C-e C-b
|
||
|
||
Toggle body-only export. Useful for excluding headers and
|
||
footers in the export. Affects only those back-end formats that
|
||
have such sections---like @samp{<head>...</head>} in HTML.
|
||
|
||
@item @{@{@{kbd(C-s@}@}@}
|
||
@kindex C-c C-e C-s
|
||
|
||
Toggle sub-tree export. When turned on, Org exports only the
|
||
sub-tree starting from the cursor position at the time the export
|
||
dispatcher was invoked. Org uses the top heading of this
|
||
sub-tree as the document's title. If the cursor is not on
|
||
a heading, Org uses the nearest enclosing header. If the cursor
|
||
is in the document preamble, Org signals an error and aborts
|
||
export.
|
||
|
||
@vindex org-export-initial-scope
|
||
To make the sub-tree export the default, customize the variable
|
||
@code{org-export-initial-scope}.
|
||
|
||
@item @kbd{C-v}
|
||
@kindex C-c C-e C-v
|
||
|
||
Toggle visible-only export. Useful for exporting only visible
|
||
parts of an Org document by adjusting outline visibility
|
||
settings.
|
||
@end table
|
||
|
||
@node Export Settings
|
||
@section Export Settings
|
||
|
||
@cindex options, for export
|
||
@cindex Export, settings
|
||
|
||
@cindex @samp{OPTIONS}, keyword
|
||
Export options can be set: globally with variables; for an individual
|
||
file by making variables buffer-local with in-buffer settings (see
|
||
@ref{In-buffer Settings}), by setting individual keywords, or by
|
||
specifying them in a compact form with the @samp{OPTIONS} keyword; or for
|
||
a tree by setting properties (see @ref{Properties and Columns}). Options
|
||
set at a specific level override options set at a more general level.
|
||
|
||
@cindex SETUPFILE, keyword
|
||
In-buffer settings may appear anywhere in the file, either directly or
|
||
indirectly through a file included using @samp{#+SETUPFILE: filename or
|
||
URL} syntax. Option keyword sets tailored to a particular back-end
|
||
can be inserted from the export dispatcher (see @ref{The Export Dispatcher}) using the @samp{Insert template} command by pressing
|
||
@kbd{#}. To insert keywords individually, a good way to make
|
||
sure the keyword is correct is to type @samp{#+} and then to use
|
||
@kbd{M-@key{TAB}}@footnote{Many desktops intercept @kbd{M-@key{TAB}} to switch windows.
|
||
Use @kbd{C-M-i} or @kbd{@key{ESC} @key{TAB}} instead.} for completion.
|
||
|
||
The export keywords available for every back-end, and their equivalent
|
||
global variables, include:
|
||
|
||
@table @asis
|
||
@item @samp{AUTHOR}
|
||
@cindex @samp{AUTHOR}, keyword
|
||
@vindex user-full-name
|
||
The document author (@code{user-full-name}).
|
||
|
||
@item @samp{CREATOR}
|
||
@cindex @samp{CREATOR}, keyword
|
||
@vindex org-expot-creator-string
|
||
Entity responsible for output generation
|
||
(@code{org-export-creator-string}).
|
||
|
||
@item @samp{DATE}
|
||
@cindex @samp{DATE}, keyword
|
||
@vindex org-export-date-timestamp-format
|
||
A date or a time-stamp@footnote{The variable @code{org-export-date-timestamp-format} defines how
|
||
this timestamp are exported.}.
|
||
|
||
@item @samp{EMAIL}
|
||
@cindex @samp{EMAIL}, keyword
|
||
@vindex user-mail-address
|
||
The email address (@code{user-mail-address}).
|
||
|
||
@item @samp{LANGUAGE}
|
||
@cindex @samp{LANGUAGE}, keyword
|
||
@vindex org-export-default-language
|
||
Language to use for translating certain strings
|
||
(@code{org-export-default-language}). With @samp{#+LANGUAGE: fr}, for
|
||
example, Org translates @samp{Table of contents} to the French @samp{Table
|
||
des matières}.
|
||
|
||
@item @samp{SELECT_TAGS}
|
||
@cindex @samp{SELECT_TAGS}, keyword
|
||
@vindex org-export-select-tags
|
||
The default value is @code{("export")}. When a tree is tagged with
|
||
@samp{export} (@code{org-export-select-tags}), Org selects that tree and
|
||
its sub-trees for export. Org excludes trees with @samp{noexport}
|
||
tags, see below. When selectively exporting files with @samp{export}
|
||
tags set, Org does not export any text that appears before the
|
||
first headline.
|
||
|
||
@item @samp{EXCLUDE_TAGS}
|
||
@cindex @samp{EXCLUDE_TAGS}, keyword
|
||
@vindex org-export-exclude-tags
|
||
The default value is @code{("noexport")}. When a tree is tagged with
|
||
@samp{noexport} (@code{org-export-exclude-tags}), Org excludes that tree
|
||
and its sub-trees from export. Entries tagged with @samp{noexport}
|
||
are unconditionally excluded from the export, even if they have
|
||
an @samp{export} tag. Even if a sub-tree is not exported, Org
|
||
executes any code blocks contained there.
|
||
|
||
@item @samp{TITLE}
|
||
@cindex @samp{TITLE}, keyword
|
||
@cindex document title
|
||
Org displays this title. For long titles, use multiple @samp{#+TITLE}
|
||
lines.
|
||
|
||
@item @samp{EXPORT_FILE_NAME}
|
||
@cindex @samp{EXPORT_FILE_NAME}, keyword
|
||
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.
|
||
@end table
|
||
|
||
The @samp{OPTIONS} keyword is a compact form. To configure multiple
|
||
options, use several @samp{OPTIONS} lines. @samp{OPTIONS} recognizes the
|
||
following arguments.
|
||
|
||
@table @asis
|
||
@item @code{'}
|
||
@vindex org-export-with-smart-quotes
|
||
Toggle smart quotes (@code{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.
|
||
|
||
@item @code{*}
|
||
@vindex org-export-with-emphasize
|
||
Toggle emphasized text (@code{org-export-with-emphasize}).
|
||
|
||
@item @code{-}
|
||
@vindex org-export-with-special-strings
|
||
Toggle conversion of special strings
|
||
(@code{org-export-with-special-strings}).
|
||
|
||
@item @code{:}
|
||
@vindex org-export-with-fixed-width
|
||
Toggle fixed-width sections (@code{org-export-with-fixed-width}).
|
||
|
||
@item @code{<}
|
||
@vindex org-export-with-timestamps
|
||
Toggle inclusion of time/date active/inactive stamps
|
||
(@code{org-export-with-timestamps}).
|
||
|
||
@item @code{\n}
|
||
@vindex org-export-preserve-breaks
|
||
Toggles whether to preserve line breaks
|
||
(@code{org-export-preserve-breaks}).
|
||
|
||
@item @code{^}
|
||
@vindex org-export-with-sub-superscripts
|
||
Toggle @TeX{}-like syntax for sub- and superscripts. If you write
|
||
@samp{^:@{@}}, @samp{a_@{b@}} is interpreted, but the simple @samp{a_b} is left as
|
||
it is (@code{org-export-with-sub-superscripts}).
|
||
|
||
@item @code{arch}
|
||
@vindex org-export-with-archived-trees
|
||
Configure how archived trees are exported. When set to
|
||
@code{headline}, the export process skips the contents and processes
|
||
only the headlines (@code{org-export-with-archived-trees}).
|
||
|
||
@item @code{author}
|
||
@vindex org-export-with-author
|
||
Toggle inclusion of author name into exported file
|
||
(@code{org-export-with-author}).
|
||
|
||
@item @code{broken-links}
|
||
@vindex org-export-with-broken-links
|
||
Toggles if Org should continue exporting upon finding a broken
|
||
internal link. When set to @code{mark}, Org clearly marks the problem
|
||
link in the output (@code{org-export-with-broken-links}).
|
||
|
||
@item @code{c}
|
||
@vindex org-export-with-clocks
|
||
Toggle inclusion of CLOCK keywords (@code{org-export-with-clocks}).
|
||
|
||
@item @code{creator}
|
||
@vindex org-export-with-creator
|
||
Toggle inclusion of creator information in the exported file
|
||
(@code{org-export-with-creator}).
|
||
|
||
@item @code{d}
|
||
@vindex org-export-with-drawers
|
||
Toggles inclusion of drawers, or list of drawers to include, or
|
||
list of drawers to exclude (@code{org-export-with-drawers}).
|
||
|
||
@item @code{date}
|
||
@vindex org-export-with-date
|
||
Toggle inclusion of a date into exported file
|
||
(@code{org-export-with-date}).
|
||
|
||
@item @code{e}
|
||
@vindex org-export-with-entities
|
||
Toggle inclusion of entities (@code{org-export-with-entities}).
|
||
|
||
@item @code{email}
|
||
@vindex org-export-with-email
|
||
Toggle inclusion of the author's e-mail into exported file
|
||
(@code{org-export-with-email}).
|
||
|
||
@item @code{f}
|
||
@vindex org-export-with-footnotes
|
||
Toggle the inclusion of footnotes (@code{org-export-with-footnotes}).
|
||
|
||
@item @code{H}
|
||
@vindex org-export-headline-levels
|
||
Set the number of headline levels for export
|
||
(@code{org-export-headline-levels}). Below that level, headlines are
|
||
treated differently. In most back-ends, they become list items.
|
||
|
||
@item @code{inline}
|
||
@vindex org-export-with-inlinetasks
|
||
Toggle inclusion of inlinetasks (@code{org-export-with-inlinetasks}).
|
||
|
||
@item @code{num}
|
||
@vindex org-export-with-section-numbers
|
||
@cindex @samp{UNNUMBERED}, property
|
||
Toggle section-numbers (@code{org-export-with-section-numbers}). When
|
||
set to number N, Org numbers only those headlines at level N or
|
||
above. Set @samp{UNNUMBERED} property to non-@code{nil} to disable
|
||
numbering of heading and subheadings entirely. Moreover, when
|
||
the value is @samp{notoc} the headline, and all its children, do not
|
||
appear in the table of contents either (see @ref{Table of Contents}).
|
||
|
||
@item @code{p}
|
||
@vindex org-export-with-planning
|
||
Toggle export of planning information
|
||
(@code{org-export-with-planning}). ``Planning information'' comes from
|
||
lines located right after the headline and contain any
|
||
combination of these cookies: @samp{SCHEDULED}, @samp{DEADLINE}, or
|
||
@samp{CLOSED}.
|
||
|
||
@item @code{pri}
|
||
@vindex org-export-with-priority
|
||
Toggle inclusion of priority cookies
|
||
(@code{org-export-with-priority}).
|
||
|
||
@item @code{prop}
|
||
@vindex org-export-with-properties
|
||
Toggle inclusion of property drawers, or list the properties to
|
||
include (@code{org-export-with-properties}).
|
||
|
||
@item @code{stat}
|
||
@vindex org-export-with-statistics-cookies
|
||
Toggle inclusion of statistics cookies
|
||
(@code{org-export-with-statistics-cookies}).
|
||
|
||
@item @code{tags}
|
||
@vindex org-export-with-tags
|
||
Toggle inclusion of tags, may also be @code{not-in-toc}
|
||
(@code{org-export-with-tags}).
|
||
|
||
@item @code{tasks}
|
||
@vindex org-export-with-tasks
|
||
Toggle inclusion of tasks (TODO items); or @code{nil} to remove all
|
||
tasks; or @code{todo} to remove DONE tasks; or list the keywords to
|
||
keep (@code{org-export-with-tasks}).
|
||
|
||
@item @code{tex}
|
||
@vindex org-export-with-latex
|
||
@code{nil} does not export; @code{t} exports; @code{verbatim} keeps everything
|
||
in verbatim (@code{org-export-with-latex}).
|
||
|
||
@item @code{timestamp}
|
||
@vindex org-export-time-stamp-file
|
||
Toggle inclusion of the creation time in the exported file
|
||
(@code{org-export-time-stamp-file}).
|
||
|
||
@item @code{title}
|
||
@vindex org-export-with-title
|
||
Toggle inclusion of title (@code{org-export-with-title}).
|
||
|
||
@item @code{toc}
|
||
@vindex org-export-with-toc
|
||
Toggle inclusion of the table of contents, or set the level limit
|
||
(@code{org-export-with-toc}).
|
||
|
||
@item @code{todo}
|
||
@vindex org-export-with-todo-keywords
|
||
Toggle inclusion of TODO keywords into exported text
|
||
(@code{org-export-with-todo-keywords}).
|
||
|
||
@item @code{|}
|
||
@vindex org-export-with-tables
|
||
Toggle inclusion of tables (@code{org-export-with-tables}).
|
||
@end table
|
||
|
||
When exporting sub-trees, special node properties in them can override
|
||
the above keywords. They are special because they have an @samp{EXPORT_}
|
||
prefix. For example, @samp{DATE} and @samp{EXPORT_FILE_NAME} keywords become,
|
||
respectively, @samp{EXPORT_DATE} and @samp{EXPORT_FILE_NAME}. Except for
|
||
@samp{SETUPFILE}, all other keywords listed above have an @samp{EXPORT_}
|
||
equivalent.
|
||
|
||
@cindex @samp{BIND}, keyword
|
||
@vindex org-export-allow-bind-keywords
|
||
If @code{org-export-allow-bind-keywords} is non-@code{nil}, Emacs variables can
|
||
become buffer-local during export by using the @samp{BIND} keyword. Its
|
||
syntax is @samp{#+BIND: variable value}. This is particularly useful for
|
||
in-buffer settings that cannot be changed using keywords.
|
||
|
||
@node Table of Contents
|
||
@section Table of Contents
|
||
|
||
@cindex table of contents
|
||
@cindex list of tables
|
||
@cindex list of listings
|
||
|
||
@cindex @samp{toc}, in @samp{OPTIONS} keyword
|
||
@vindex org-export-with-toc
|
||
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
|
||
@code{org-export-with-toc} variable accordingly. You can achieve the same
|
||
on a per file basis, using the following @samp{toc} item in @samp{OPTIONS}
|
||
keyword:
|
||
|
||
@example
|
||
#+OPTIONS: toc:2 (only include two levels in TOC)
|
||
#+OPTIONS: toc:nil (no default TOC at all)
|
||
@end example
|
||
|
||
@cindex excluding entries from table of contents
|
||
@cindex table of contents, exclude entries
|
||
Org includes both numbered and unnumbered headlines in the table of
|
||
contents@footnote{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.}. If you need to exclude an unnumbered headline,
|
||
along with all its children, set the @samp{UNNUMBERED} property to @samp{notoc}
|
||
value.
|
||
|
||
@example
|
||
* Subtree not numbered, not in table of contents either
|
||
:PROPERTIES:
|
||
:UNNUMBERED: notoc
|
||
:END:
|
||
@end example
|
||
|
||
@cindex @samp{TOC}, keyword
|
||
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 @code{org-export-with-toc}
|
||
variable or with @samp{#+OPTIONS: toc:nil}. Then insert @samp{#+TOC: headlines
|
||
N} at the desired location(s).
|
||
|
||
@example
|
||
#+OPTIONS: toc:nil
|
||
...
|
||
#+TOC: headlines 2
|
||
@end example
|
||
|
||
To adjust the table of contents depth for a specific section of the
|
||
Org document, append an additional @samp{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.
|
||
|
||
@example
|
||
* Section
|
||
#+TOC: headlines 1 local
|
||
@end example
|
||
|
||
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 @emph{before} hyperref.
|
||
Customize the @code{org-latex-default-packages-alist} variable.
|
||
|
||
Use the @samp{TOC} keyword to generate list of tables---respectively, all
|
||
listings---with captions.
|
||
|
||
@example
|
||
#+TOC: listings
|
||
#+TOC: tables
|
||
@end example
|
||
|
||
@cindex @samp{ALT_TITLE}, property
|
||
Normally Org uses the headline for its entry in the table of contents.
|
||
But with @samp{ALT_TITLE} property, a different entry can be specified for
|
||
the table of contents.
|
||
|
||
@node Include Files
|
||
@section Include Files
|
||
|
||
@cindex include files, during export
|
||
@cindex Export, include files
|
||
@cindex @samp{INCLUDE}, keyword
|
||
|
||
During export, you can include the content of another file. For
|
||
example, to include your @samp{.emacs} file, you could use:
|
||
|
||
@example
|
||
#+INCLUDE: "~/.emacs" src emacs-lisp
|
||
@end example
|
||
|
||
@noindent
|
||
The optional second and third parameter are the markup (e.g., @samp{quote},
|
||
@samp{example}, or @samp{src}), and, if the markup is @samp{src}, the language for
|
||
formatting the contents. The markup is optional; if it is not given,
|
||
assume text is in Org syntax and process it normally. The @samp{INCLUDE}
|
||
keyword also allows additional parameters @samp{:prefix1} and @samp{:prefix} to
|
||
specify prefixes for the first line and for each following line,
|
||
@samp{:minlevel} in order to get Org mode content demoted to a specified
|
||
level, as well as any options accepted by the selected markup. For
|
||
example, to include a file as an item, use:
|
||
|
||
@example
|
||
#+INCLUDE: "~/snippets/xx" :prefix1 " + " :prefix " "
|
||
@end example
|
||
|
||
You can also include a portion of a file by specifying a lines range
|
||
using the @samp{:lines} parameter. The line at the upper end of the range
|
||
is not included. The start and/or the end of the range may be omitted
|
||
to use the obvious defaults.
|
||
|
||
@table @asis
|
||
@item @samp{#+INCLUDE: "~/.emacs" :lines "5-10"}
|
||
Include lines 5 to 10, 10 excluded.
|
||
|
||
@item @samp{#+INCLUDE: "~/.emacs" :lines "-10"}
|
||
Include lines 1 to 10, 10 excluded.
|
||
|
||
@item @samp{#+INCLUDE: "~/.emacs" :lines "10-"}
|
||
Include lines from 10 to EOF.
|
||
@end table
|
||
|
||
You can visit the file being included with the following command.
|
||
|
||
@table @asis
|
||
@item @kbd{C-c '} (@code{org-edit~special})
|
||
@kindex C-c '
|
||
@findex org-edit-special
|
||
|
||
Visit the include file at point.
|
||
@end table
|
||
|
||
@node Macro Replacement
|
||
@section Macro Replacement
|
||
|
||
@cindex macro replacement, during export
|
||
@cindex @samp{MACRO}, keyword
|
||
|
||
@vindex org-export-global-macros
|
||
Macros replace text snippets during export. Macros are defined
|
||
globally in @code{org-export-global-macros}, or document-wise with the
|
||
following syntax:
|
||
|
||
@example
|
||
#+MACRO: name replacement text; $1, $2 are arguments
|
||
@end example
|
||
|
||
@noindent
|
||
which can be referenced using @samp{@{@{@{name(arg1, arg2)@}@}@}}@footnote{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.}. For
|
||
example
|
||
|
||
@example
|
||
#+MACRO: poem The rose is $1, The violet's $2. Life's ordered: Org assists you.
|
||
@{@{@{poem(red,blue)@}@}@}
|
||
@end example
|
||
|
||
@noindent
|
||
becomes
|
||
|
||
@example
|
||
The rose is red, The violet's blue. Life's ordered: Org assists you.
|
||
@end example
|
||
|
||
As a special case, Org parses any replacement text starting with
|
||
@samp{(eval} as an Emacs Lisp expression and evaluates it accordingly.
|
||
Within such templates, arguments become strings. Thus, the following
|
||
macro
|
||
|
||
@example
|
||
#+MACRO: gnucheck (eval (concat "GNU/" (capitalize $1)))
|
||
@end example
|
||
|
||
@noindent
|
||
turns @samp{@{@{@{gnucheck(linux)@}@}@}} into @samp{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 @samp{CAPTION}, @samp{TITLE},
|
||
@samp{AUTHOR}, @samp{DATE}, and for some back-end specific export options.
|
||
|
||
Org comes with following pre-defined macros:
|
||
|
||
@table @asis
|
||
@item @samp{@{@{@{keyword(NAME)@}@}@}}
|
||
@itemx @samp{@{@{@{title@}@}@}}
|
||
@itemx @samp{@{@{@{author@}@}@}}
|
||
@itemx @samp{@{@{@{email@}@}@}}
|
||
@cindex @samp{keyword}, macro
|
||
@cindex @samp{title}, macro
|
||
@cindex @samp{author}, macro
|
||
@cindex @samp{email}, macro
|
||
The @samp{keyword} macro collects all values from @var{NAME}
|
||
keywords throughout the buffer, separated with white space.
|
||
@samp{title}, @samp{author} and @samp{email} macros are shortcuts for,
|
||
respectively, @samp{@{@{@{keyword(TITLE)@}@}@}}, @samp{@{@{@{keyword(AUTHOR)@}@}@}} and
|
||
@samp{@{@{@{keyword(EMAIL)@}@}@}}.
|
||
|
||
@item @samp{@{@{@{date@}@}@}}
|
||
@itemx @samp{@{@{@{date(FORMAT)@}@}@}}
|
||
@cindex @samp{date}, macro
|
||
This macro refers to the @samp{DATE} keyword. @var{FORMAT} is an
|
||
optional argument to the @samp{date} macro that is used only if @samp{DATE}
|
||
is a single timestamp. @var{FORMAT} should be a format
|
||
string understood by @code{format-time-string}.
|
||
|
||
@item @samp{@{@{@{time(FORMAT)@}@}@}}
|
||
@itemx @samp{@{@{@{modification-time(FORMAT, VC)@}@}@}}
|
||
@cindex @samp{time}, macro
|
||
@cindex @samp{modification-time}, macro
|
||
These macros refer to the document's date and time of export and
|
||
date and time of modification. @var{FORMAT} is a string
|
||
understood by @code{format-time-string}. If the second argument to
|
||
the @code{modification-time} macro is non-@code{nil}, Org uses @samp{vc.el} to
|
||
retrieve the document's modification time from the version
|
||
control system. Otherwise Org reads the file attributes.
|
||
|
||
@item @samp{@{@{@{input-file@}@}@}}
|
||
@cindex @samp{input-file}, macro
|
||
This macro refers to the filename of the exported file.
|
||
|
||
@item @samp{@{@{@{property(PROPERTY-NAME)@}@}@}}
|
||
@itemx @samp{@{@{@{property(PROPERTY-NAME, SEARCH OPTION)@}@}@}}
|
||
@cindex @samp{property}, macro
|
||
This macro returns the value of property @var{PROPERTY-NAME}
|
||
in the current entry. If @var{SEARCH-OPTION} (see @ref{Search Options}) refers to a remote entry, use it instead.
|
||
|
||
@item @samp{@{@{@{n@}@}@}}
|
||
@itemx @samp{@{@{@{n(NAME)@}@}@}}
|
||
@itemx @samp{@{@{@{n(NAME, ACTION)@}@}@}}
|
||
@cindex @samp{n}, macro
|
||
@cindex counter, macro
|
||
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
|
||
@var{NAME} values. If @var{ACTION} is @samp{-}, 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 @var{NAME}
|
||
empty to reset the default counter.
|
||
@end table
|
||
|
||
@vindex org-hide-macro-markers
|
||
The surrounding brackets can be made invisible by setting
|
||
@code{org-hide-macro-markers} non-@code{nil}.
|
||
|
||
Org expands macros at the very beginning of the export process.
|
||
|
||
@node Comment Lines
|
||
@section Comment Lines
|
||
|
||
@cindex exporting, not
|
||
|
||
@cindex comment lines
|
||
Lines starting with zero or more whitespace characters followed by one
|
||
@samp{#} and a whitespace are treated as comments and, as such, are not
|
||
exported.
|
||
|
||
@cindex @samp{BEGIN_COMMENT}
|
||
@cindex comment block
|
||
Likewise, regions surrounded by @samp{#+BEGIN_COMMENT} @dots{} @samp{#+END_COMMENT}
|
||
are not exported.
|
||
|
||
@cindex comment trees
|
||
Finally, a @samp{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@footnote{For a less drastic behavior, consider using a select tag (see
|
||
@ref{Export Settings}) instead.}. The command below helps changing the
|
||
comment status of a headline.
|
||
|
||
@table @asis
|
||
@item @kbd{C-c ;} (@code{org-toggle-comment})
|
||
@kindex C-c ;
|
||
@findex org-toggle-comment
|
||
|
||
Toggle the @samp{COMMENT} keyword at the beginning of an entry.
|
||
@end table
|
||
|
||
@node ASCII/Latin-1/UTF-8 export
|
||
@section ASCII/Latin-1/UTF-8 export
|
||
|
||
@cindex ASCII export
|
||
@cindex Latin-1 export
|
||
@cindex 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.
|
||
|
||
@vindex org-ascii-text-width
|
||
On export, Org fills and justifies text according to the text width
|
||
set in @code{org-ascii-text-width}.
|
||
|
||
@vindex org-ascii-links-to-notes
|
||
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 @code{org-ascii-links-to-notes} for details.
|
||
|
||
@anchor{ASCII export commands}
|
||
@subheading ASCII export commands
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-e t a} (@code{org-ascii-export-to-ascii})
|
||
@itemx @kbd{C-c C-e t l}
|
||
@itemx @kbd{C-c C-e t u}
|
||
@kindex C-c C-e t a
|
||
@kindex C-c C-e t l
|
||
@kindex C-c C-e t u
|
||
@findex org-ascii-export-to-ascii
|
||
|
||
Export as an ASCII file with a @samp{.txt} extension. For
|
||
@samp{myfile.org}, Org exports to @samp{myfile.txt}, overwriting without
|
||
warning. For @samp{myfile.txt}, Org exports to @samp{myfile.txt.txt} in
|
||
order to prevent data loss.
|
||
@end table
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-e t A} (@code{org-ascii-export-to-ascii})
|
||
@itemx @kbd{C-c C-e t L}
|
||
@itemx @kbd{C-c C-e t U}
|
||
@kindex C-c C-e t A
|
||
@kindex C-c C-e t L
|
||
@kindex C-c C-e t U
|
||
@findex org-ascii-export-to-ascii
|
||
|
||
Export to a temporary buffer. Does not create a file.
|
||
@end table
|
||
|
||
@anchor{ASCII specific export settings}
|
||
@subheading 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 @ref{Export Settings}).
|
||
|
||
@table @asis
|
||
@item @samp{SUBTITLE}
|
||
@cindex @samp{SUBTITLE}, keyword
|
||
The document subtitle. For long subtitles, use multiple
|
||
@samp{#+SUBTITLE} lines in the Org file. Org prints them on one
|
||
continuous line, wrapping into multiple lines if necessary.
|
||
@end table
|
||
|
||
@anchor{Header and sectioning structure}
|
||
@subheading 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 @ref{Export Settings}.
|
||
|
||
@anchor{Quoting ASCII text}
|
||
@subheading 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:
|
||
|
||
@cindex @samp{ASCII}, keyword
|
||
@cindex @samp{BEGIN_EXPORT ascii}
|
||
@example
|
||
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
|
||
@end example
|
||
|
||
@anchor{ASCII specific attributes}
|
||
@subheading ASCII specific attributes
|
||
|
||
@cindex @samp{ATTR_ASCII}, keyword
|
||
@cindex horizontal rules, in ASCII export
|
||
|
||
ASCII back-end recognizes only one attribute, @code{:width}, which
|
||
specifies the width of an horizontal rule in number of characters.
|
||
The keyword and syntax for specifying widths is:
|
||
|
||
@example
|
||
#+ATTR_ASCII: :width 10
|
||
-----
|
||
@end example
|
||
|
||
@anchor{ASCII special blocks}
|
||
@subheading ASCII special blocks
|
||
|
||
@cindex special blocks, in ASCII export
|
||
@cindex @samp{BEGIN_JUSTIFYLEFT}
|
||
@cindex @samp{BEGIN_JUSTIFYRIGHT}
|
||
|
||
Besides @samp{#+BEGIN_CENTER} blocks (see @ref{Paragraphs}), ASCII back-end has
|
||
these two left and right justification blocks:
|
||
|
||
@example
|
||
#+BEGIN_JUSTIFYLEFT
|
||
It's just a jump to the left...
|
||
#+END_JUSTIFYLEFT
|
||
|
||
#+BEGIN_JUSTIFYRIGHT
|
||
...and then a step to the right.
|
||
#+END_JUSTIFYRIGHT
|
||
@end example
|
||
|
||
@node Beamer Export
|
||
@section Beamer Export
|
||
|
||
@cindex 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.
|
||
@end menu
|
||
|
||
@node Beamer export commands
|
||
@subsection Beamer export commands
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-e l b} (@code{org-beamer-export-to-latex})
|
||
@kindex C-c C-e l b
|
||
@findex org-beamer-export-to-latex
|
||
|
||
Export as @LaTeX{} file with a @samp{.tex} extension. For @samp{myfile.org},
|
||
Org exports to @samp{myfile.tex}, overwriting without warning.
|
||
|
||
@item @kbd{C-c C-e l B} (@code{org-beamer-export-as-latex})
|
||
@kindex C-c C-e l B
|
||
@findex org-beamer-export-as-latex
|
||
|
||
Export to a temporary buffer. Does not create a file.
|
||
|
||
@item @kbd{C-c C-e l P} (@code{org-beamer-export-to-pdf})
|
||
@kindex C-c C-e l P
|
||
@findex org-beamer-export-to-pdf
|
||
|
||
Export as @LaTeX{} file and then convert it to PDF format.
|
||
|
||
@item @kbd{C-c C-e l O}
|
||
@kindex C-c C-e l O
|
||
|
||
Export as @LaTeX{} file, convert it to PDF format, and then open the
|
||
PDF file.
|
||
@end table
|
||
|
||
@node Beamer specific export settings
|
||
@subsection 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 @ref{Export Settings}).
|
||
|
||
@table @asis
|
||
@item @samp{BEAMER_THEME}
|
||
@cindex @samp{BEAMER_THEME}, keyword
|
||
@vindex org-beamer-theme
|
||
The Beamer layout theme (@code{org-beamer-theme}). Use square
|
||
brackets for options. For example:
|
||
|
||
@example
|
||
#+BEAMER_THEME: Rochester [height=20pt]
|
||
@end example
|
||
|
||
@item @samp{BEAMER_FONT_THEME}
|
||
@cindex @samp{BEAMER_FONT_THEME}, keyword
|
||
The Beamer font theme.
|
||
|
||
@item @samp{BEAMER_INNER_THEME}
|
||
@cindex @samp{BEAMER_INNER_THEME}, keyword
|
||
The Beamer inner theme.
|
||
|
||
@item @samp{BEAMER_OUTER_THEME}
|
||
@cindex @samp{BEAMER_OUTER_THEME}, keyword
|
||
The Beamer outer theme.
|
||
|
||
@item @samp{BEAMER_HEADER}
|
||
@cindex @samp{BEAMER_HEADER}, keyword
|
||
Arbitrary lines inserted in the preamble, just before the
|
||
@samp{hyperref} settings.
|
||
|
||
@item @samp{DESCRIPTION}
|
||
@cindex @samp{DESCRIPTION}, keyword
|
||
The document description. For long descriptions, use multiple
|
||
@samp{DESCRIPTION} keywords. By default, @samp{hyperref} inserts
|
||
@samp{DESCRIPTION} as metadata. Use @code{org-latex-hyperref-template} to
|
||
configure document metadata. Use @code{org-latex-title-command} to
|
||
configure typesetting of description as part of front matter.
|
||
|
||
@item @samp{KEYWORDS}
|
||
@cindex @samp{KEYWORDS}, keyword
|
||
The keywords for defining the contents of the document. Use
|
||
multiple @samp{KEYWORDS} lines if necessary. By default, @samp{hyperref}
|
||
inserts @samp{KEYWORDS} as metadata. Use
|
||
@code{org-latex-hyperref-template} to configure document metadata.
|
||
Use @code{org-latex-title-command} to configure typesetting of
|
||
keywords as part of front matter.
|
||
|
||
@item @samp{SUBTITLE}
|
||
@cindex @samp{SUBTITLE}, keyword
|
||
Document's subtitle. For typesetting, use
|
||
@code{org-beamer-subtitle-format} string. Use
|
||
@code{org-latex-hyperref-template} to configure document metadata.
|
||
Use @code{org-latex-title-command} to configure typesetting of
|
||
subtitle as part of front matter.
|
||
@end table
|
||
|
||
@node Frames and Blocks in Beamer
|
||
@subsection 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.
|
||
|
||
@itemize
|
||
@item
|
||
@vindex org-beamer-frame-level
|
||
Org headlines become Beamer frames when the heading level in Org is
|
||
equal to @code{org-beamer-frame-level} or @samp{H} value in a @samp{OPTIONS} line
|
||
(see @ref{Export Settings}).
|
||
|
||
@cindex @samp{BEAMER_ENV}, property
|
||
Org overrides headlines to frames conversion for the current tree of
|
||
an Org file if it encounters the @samp{BEAMER_ENV} property set to
|
||
@samp{frame} or @samp{fullframe}. Org ignores whatever
|
||
@code{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.
|
||
|
||
@item
|
||
Org exports a Beamer frame's objects as block environments. Org can
|
||
enforce wrapping in special block types when @samp{BEAMER_ENV} property
|
||
is set@footnote{If @samp{BEAMER_ENV} is set, Org export adds @samp{B_environment} tag
|
||
to make it visible. The tag serves as a visual aid and has no
|
||
semantic relevance.}. For valid values see
|
||
@code{org-beamer-environments-default}. To add more values, see
|
||
@code{org-beamer-environments-extra}.
|
||
@vindex org-beamer-environments-default
|
||
@vindex org-beamer-environments-extra
|
||
|
||
@item
|
||
@cindex @samp{BEAMER_REF}, property
|
||
If @samp{BEAMER_ENV} is set to @samp{appendix}, Org exports the entry as an
|
||
appendix. When set to @samp{note}, Org exports the entry as a note
|
||
within the frame or between frames, depending on the entry's heading
|
||
level. When set to @samp{noteNH}, Org exports the entry as a note
|
||
without its title. When set to @samp{againframe}, Org exports the entry
|
||
with @samp{\againframe} command, which makes setting the @samp{BEAMER_REF}
|
||
property mandatory because @samp{\againframe} needs frame to resume.
|
||
|
||
When @samp{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 @samp{column}
|
||
environment. @@end itemize
|
||
|
||
@cindex @samp{BEAMER_ACT}, property
|
||
@cindex @samp{BEAMER_OPT}, property
|
||
When @samp{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 @samp{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
|
||
@samp{fragile} option for any code that may require a verbatim block.
|
||
|
||
@cindex @samp{BEAMER_COL}, property
|
||
To create a column on the Beamer slide, use the @samp{BEAMER_COL}
|
||
property for its headline in the Org file. Set the value of
|
||
@samp{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 @samp{BEAMER_ENV} property.
|
||
@end itemize
|
||
|
||
@node Beamer specific syntax
|
||
@subsection 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,
|
||
@samp{#+LATEX:} or @samp{#+ATTR_LATEX:}. See @ref{@LaTeX{} Export}, for details.
|
||
|
||
Beamer export wraps the table of contents generated with @samp{toc:t}
|
||
@samp{OPTION} keyword in a @samp{frame} environment. Beamer export does not
|
||
wrap the table of contents generated with @samp{TOC} keyword (see @ref{Table of Contents}). Use square brackets for specifying options.
|
||
|
||
@example
|
||
#+TOC: headlines [currentsection]
|
||
@end example
|
||
|
||
Insert Beamer-specific code using the following constructs:
|
||
|
||
@cindex @samp{BEAMER}, keyword
|
||
@cindex @samp{BEGIN_EXPORT beamer}
|
||
@example
|
||
#+BEAMER: \pause
|
||
|
||
#+BEGIN_EXPORT beamer
|
||
Only Beamer export back-end exports this.
|
||
#+END_BEAMER
|
||
|
||
Text @@@@beamer:some code@@@@ within a paragraph.
|
||
@end example
|
||
|
||
Inline constructs, such as the last one above, are useful for adding
|
||
overlay specifications to objects with @code{bold}, @code{item}, @code{link},
|
||
@code{radio-target} and @code{target} types. Enclose the value in angular
|
||
brackets and place the specification at the beginning of the object as
|
||
shown in this example:
|
||
|
||
@example
|
||
A *@@@@beamer:<2->@@@@useful* feature
|
||
@end example
|
||
|
||
@cindex @samp{ATTR_BEAMER}, keyword
|
||
Beamer export recognizes the @samp{ATTR_BEAMER} keyword with the following
|
||
attributes from Beamer configurations: @samp{:environment} for changing
|
||
local Beamer environment, @samp{:overlay} for specifying Beamer overlays in
|
||
angular or square brackets, and @samp{:options} for inserting optional
|
||
arguments.
|
||
|
||
@example
|
||
#+ATTR_BEAMER: :environment nonindentlist
|
||
- item 1, not indented
|
||
- item 2, not indented
|
||
- item 3, not indented
|
||
@end example
|
||
|
||
@example
|
||
#+ATTR_BEAMER: :overlay <+->
|
||
- item 1
|
||
- item 2
|
||
@end example
|
||
|
||
@example
|
||
#+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$.
|
||
@end example
|
||
|
||
@node Editing support
|
||
@subsection Editing support
|
||
|
||
The @code{org-beamer-mode} is a special minor mode for faster editing of
|
||
Beamer documents.
|
||
|
||
@example
|
||
#+STARTUP: beamer
|
||
@end example
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-b} (@code{org-beamer-select-environment})
|
||
@kindex C-c C-b
|
||
@findex org-beamer-select-environment
|
||
|
||
The @code{org-beamer-mode} provides this key for quicker selections in
|
||
Beamer normal environments, and for selecting the @samp{BEAMER_COL}
|
||
property.
|
||
@end table
|
||
|
||
@node A Beamer example
|
||
@subsection A Beamer example
|
||
|
||
Here is an example of an Org document ready for Beamer export.
|
||
|
||
@example
|
||
;#+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) %8BEAMER_OPT(Opt)
|
||
|
||
* 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!
|
||
@end example
|
||
|
||
@node HTML Export
|
||
@section HTML Export
|
||
|
||
@cindex 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.
|
||
* 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.
|
||
@end menu
|
||
|
||
@node HTML export commands
|
||
@subsection HTML export commands
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-e h h} (@code{org-html-export-to-html})
|
||
@kindex C-c C-e h h
|
||
@kindex C-c C-e h o
|
||
@findex org-html-export-to-html
|
||
|
||
Export as HTML file with a @samp{.html} extension. For @samp{myfile.org},
|
||
Org exports to @samp{myfile.html}, overwriting without warning.
|
||
@{@{@{kbd@{C-c C-e h o)@}@}@} exports to HTML and opens it in a web
|
||
browser.
|
||
|
||
@item @kbd{C-c C-e h H} (@code{org-html-export-as-html})
|
||
@kindex C-c C-e h H
|
||
@findex org-html-export-as-html
|
||
|
||
Exports to a temporary buffer. Does not create a file.
|
||
@end table
|
||
|
||
@node HTML specific export settings
|
||
@subsection HTML specific export settings
|
||
|
||
HTML export has a number of keywords, similar to the general options
|
||
settings described in @ref{Export Settings}.
|
||
|
||
@table @asis
|
||
@item @samp{DESCRIPTION}
|
||
@cindex @samp{DESCRIPTION}, keyword
|
||
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 @samp{DESCRIPTION} lines. The exporter
|
||
takes care of wrapping the lines properly.
|
||
|
||
@item @samp{HTML_DOCTYPE}
|
||
@cindex @samp{HTML_DOCTYPE}, keyword
|
||
@vindex org-html-doctype
|
||
Specify the document type, for example: HTML5
|
||
(@code{org-html-doctype}).
|
||
|
||
@item @samp{HTML_CONTAINER}
|
||
@cindex @samp{HTML_CONTAINER}, keyword
|
||
@vindex org-html-container-element
|
||
Specify the HTML container, such as @samp{div}, for wrapping sections
|
||
and elements (@code{org-html-container-element}).
|
||
|
||
@item @samp{HTML_LINK_HOME}
|
||
@cindex @samp{HTML_LINK_HOME}, keyword
|
||
@vindex org-html-link-home
|
||
The URL for home link (@code{org-html-link-home}).
|
||
|
||
@item @samp{HTML_LINK_UP}
|
||
@cindex @samp{HTML_LINK_UP}, keyword
|
||
@vindex org-html-link-up
|
||
The URL for the up link of exported HTML pages
|
||
(@code{org-html-link-up}).
|
||
|
||
@item @samp{HTML_MATHJAX}
|
||
@cindex @samp{HTML_MATHJAX}, keyword
|
||
@vindex org-html-mathjax-options
|
||
Options for MathJax (@code{org-html-mathjax-options}). MathJax is
|
||
used to typeset @LaTeX{} math in HTML documents. See @ref{Math formatting in HTML export}, for an example.
|
||
|
||
@item @samp{HTML_HEAD}
|
||
@cindex @samp{HTML_HEAD}, keyword
|
||
@vindex org-html-head
|
||
Arbitrary lines for appending to the HTML document's head
|
||
(@code{org-html-head}).
|
||
|
||
@item @samp{HTML_HEAD_EXTRA}
|
||
@cindex @samp{HTML_HEAD_EXTRA}, keyword
|
||
@vindex org-html-head-extra
|
||
More arbitrary lines for appending to the HTML document's head
|
||
(@code{org-html-head-extra}).
|
||
|
||
@item @samp{KEYWORDS}
|
||
@cindex @samp{KEYWORDS}, keyword
|
||
Keywords to describe the document's content. HTML exporter
|
||
inserts these keywords as HTML meta tags. For long keywords, use
|
||
multiple @samp{KEYWORDS} lines.
|
||
|
||
@item @samp{LATEX_HEADER}
|
||
@cindex @samp{LATEX_HEADER}, keyword
|
||
Arbitrary lines for appending to the preamble; HTML exporter
|
||
appends when transcoding @LaTeX{} fragments to images (see @ref{Math formatting in HTML export}).
|
||
|
||
@item @samp{SUBTITLE}
|
||
@cindex @samp{SUBTITLE}, keyword
|
||
The document's subtitle. HTML exporter formats subtitle if
|
||
document type is @samp{HTML5} and the CSS has a @samp{subtitle} class.
|
||
@end table
|
||
|
||
Some of these keywords are explained in more detail in the following
|
||
sections of the manual.
|
||
|
||
@node HTML doctypes
|
||
@subsection HTML doctypes
|
||
|
||
Org can export to various (X)HTML flavors.
|
||
|
||
@vindex org-html-doctype
|
||
@vindex org-html-doctype-alist
|
||
Set the @code{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:
|
||
|
||
@itemize
|
||
@item
|
||
@code{"html4-strict"}
|
||
@item
|
||
@code{"html4-transitional"}
|
||
@item
|
||
@code{"html4-frameset"}
|
||
@item
|
||
@code{"xhtml-strict"}
|
||
@item
|
||
@code{"xhtml-transitional"}
|
||
@item
|
||
@code{"xhtml-frameset"}
|
||
@item
|
||
@code{"xhtml-11"}
|
||
@item
|
||
@code{"html5"}
|
||
@item
|
||
@code{"xhtml5"}
|
||
@end itemize
|
||
|
||
@noindent
|
||
See the variable @code{org-html-doctype-alist} for details. The default is
|
||
@code{"xhtml-strict"}.
|
||
|
||
@vindex org-html-html5-fancy
|
||
@cindex @samp{HTML5}, export new elements
|
||
Org's HTML exporter does not by default enable new block elements
|
||
introduced with the HTML5 standard. To enable them, set
|
||
@code{org-html-html5-fancy} to non-@code{nil}. Or use an @samp{OPTIONS} line in the
|
||
file to set @samp{html5-fancy}.
|
||
|
||
HTML5 documents can now have arbitrary @samp{#+BEGIN} @dots{} @samp{#+END} blocks.
|
||
For example:
|
||
|
||
@example
|
||
#+BEGIN_aside
|
||
Lorem ipsum
|
||
#+END_aside
|
||
@end example
|
||
|
||
@noindent
|
||
exports to:
|
||
|
||
@example
|
||
<aside>
|
||
<p>Lorem ipsum</p>
|
||
</aside>
|
||
@end example
|
||
|
||
@noindent
|
||
while this:
|
||
|
||
@example
|
||
#+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
|
||
@end example
|
||
|
||
@noindent
|
||
exports to:
|
||
|
||
@example
|
||
<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>
|
||
@end example
|
||
|
||
@vindex org-html-html5-elements
|
||
When special blocks do not have a corresponding HTML5 element, the
|
||
HTML exporter reverts to standard translation (see
|
||
@code{org-html-html5-elements}). For example, @samp{#+BEGIN_lederhosen} exports
|
||
to @code{<div class="lederhosen">}.
|
||
|
||
Special blocks cannot have headlines. For the HTML exporter to wrap
|
||
the headline and its contents in @code{<section>} or @code{<article>} tags, set
|
||
the @samp{HTML_CONTAINER} property for the headline.
|
||
|
||
@node HTML preamble and postamble
|
||
@subsection HTML preamble and postamble
|
||
|
||
@vindex org-html-preamble
|
||
@vindex org-html-postamble
|
||
@vindex org-html-preamble-format
|
||
@vindex org-html-postamble-format
|
||
@vindex org-html-validation-link
|
||
@vindex org-export-creator-string
|
||
@vindex org-export-time-stamp-file
|
||
|
||
The HTML exporter has delineations for preamble and postamble. The
|
||
default value for @code{org-html-preamble} is @code{t}, which makes the HTML
|
||
exporter insert the preamble. See the variable
|
||
@code{org-html-preamble-format} for the format string.
|
||
|
||
Set @code{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 @code{org-html-preamble} is set @code{nil}.
|
||
|
||
The default value for @code{org-html-postamble} is @code{auto}, which makes the
|
||
HTML exporter build a postamble from looking up author's name, email
|
||
address, creator's name, and date. Set @code{org-html-postamble} to @code{t} to
|
||
insert the postamble in the format specified in the
|
||
@code{org-html-postamble-format} variable. The HTML exporter does not
|
||
insert a postamble if @code{org-html-postamble} is set to @code{nil}.
|
||
|
||
@node Quoting HTML tags
|
||
@subsection Quoting HTML tags
|
||
|
||
The HTML export back-end transforms @samp{<} and @samp{>} to @samp{<} and @samp{>}.
|
||
|
||
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:
|
||
@samp{@@@@html:...@@@@}. For example:
|
||
|
||
@example
|
||
@@@@html:<b>@@@@bold text@@@@html:</b>@@@@
|
||
@end example
|
||
|
||
@cindex @samp{HTML}, keyword
|
||
@cindex @samp{BEGIN_EXPORT html}
|
||
For larger raw HTML code blocks, use these HTML export code blocks:
|
||
|
||
@example
|
||
#+HTML: Literal HTML code for export
|
||
|
||
#+BEGIN_EXPORT html
|
||
All lines between these markers are exported literally
|
||
#+END_EXPORT
|
||
@end example
|
||
|
||
@node Links in HTML export
|
||
@subsection Links in HTML export
|
||
|
||
@cindex links, in HTML export
|
||
@cindex internal links, in HTML export
|
||
@cindex external links, in HTML export
|
||
|
||
The HTML export back-end transforms Org's internal links (see
|
||
@ref{Internal Links}) to equivalent HTML links in the output. The back-end
|
||
similarly handles Org's automatic links created by radio targets (see
|
||
@ref{Radio Targets}) similarly. For Org links to external files, the
|
||
back-end transforms the links to @emph{relative} paths.
|
||
|
||
@vindex org-html-link-org-files-as-html
|
||
For Org links to other @samp{.org} files, the back-end automatically
|
||
changes the file extension to @samp{.html} and makes file paths relative.
|
||
If the @samp{.org} files have an equivalent @samp{.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 @code{org-html-link-org-files-as-html} to @code{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 @ref{Publishing links}.
|
||
|
||
Org files can also have special directives to the HTML export
|
||
back-end. For example, by using @samp{#+ATTR_HTML} lines to specify new
|
||
format attributes to @code{<a>} or @code{<img>} tags. This example shows
|
||
changing the link's title and style:
|
||
|
||
@cindex @samp{ATTR_HTML}, keyword
|
||
@example
|
||
#+ATTR_HTML: :title The Org mode homepage :style color:red;
|
||
[[https://orgmode.org]]
|
||
@end example
|
||
|
||
@node Tables in HTML export
|
||
@subsection Tables in HTML export
|
||
|
||
@cindex tables, in HTML
|
||
@vindex org-export-html-table-tag
|
||
|
||
The HTML export back-end uses @code{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:
|
||
|
||
@cindex @samp{CAPTION}, keyword
|
||
@cindex @samp{ATTR_HTML}, keyword
|
||
@example
|
||
#+CAPTION: This is a table with lines around and between cells
|
||
#+ATTR_HTML: border="2" rules="all" frame="border"
|
||
@end example
|
||
|
||
The HTML export back-end preserves column groupings in Org tables (see
|
||
@ref{Column Groups}) when exporting to HTML.
|
||
|
||
Additional options for customizing tables for HTML export.
|
||
|
||
@table @asis
|
||
@item @code{org-html-table-align-individual-fields}
|
||
@vindex org-html-table-align-individual-fields
|
||
Non-@code{nil} attaches style attributes for alignment to each table
|
||
field.
|
||
|
||
@item @code{org-html-table-caption-above}
|
||
@vindex org-html-table-caption-above
|
||
Non-@code{nil} places caption string at the beginning of the table.
|
||
|
||
@item @code{org-html-table-data-tags}
|
||
@vindex org-html-table-data-tags
|
||
Opening and ending tags for table data fields.
|
||
|
||
@item @code{org-html-table-default-attributes}
|
||
@vindex org-html-table-default-attributes
|
||
Default attributes and values for table tags.
|
||
|
||
@item @code{org-html-table-header-tags}
|
||
@vindex org-html-table-header-tags
|
||
Opening and ending tags for table's header fields.
|
||
|
||
@item @code{org-html-table-row-tags}
|
||
@vindex org-html-table-row-tags
|
||
Opening and ending tags for table rows.
|
||
|
||
@item @code{org-html-table-use-header-tags-for-first-column}
|
||
@vindex org-html-table-use-header-tags-for-first-column
|
||
Non-@code{nil} formats column one in tables with header tags.
|
||
@end table
|
||
|
||
@node Images in HTML export
|
||
@subsection Images in HTML export
|
||
|
||
@cindex images, inline in HTML
|
||
@cindex inlining images in HTML
|
||
|
||
The HTML export back-end has features to convert Org image links to
|
||
HTML inline images and HTML clickable image links.
|
||
|
||
@vindex org-html-inline-images
|
||
When the link in the Org file has no description, the HTML export
|
||
back-end by default in-lines that image. For example:
|
||
@samp{[[file:myimg.jpg]]} is in-lined, while @samp{[[file:myimg.jpg][the image]]} links to the text,
|
||
@samp{the image}. For more details, see the variable
|
||
@code{org-html-inline-images}.
|
||
|
||
On the other hand, if the description part of the Org link is itself
|
||
another link, such as @samp{file:} or @samp{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:
|
||
|
||
@example
|
||
[[file:highres.jpg][file:thumb.jpg]]
|
||
@end example
|
||
|
||
To change attributes of in-lined images, use @samp{#+ATTR_HTML} lines in
|
||
the Org file. This example shows realignment to right, and adds @code{alt}
|
||
and @code{title} attributes in support of text viewers and modern web
|
||
accessibility standards.
|
||
|
||
@cindex @samp{CAPTION}, keyword
|
||
@cindex @samp{ATTR_HTML}, keyword
|
||
@example
|
||
#+CAPTION: A black cat stalking a spider
|
||
#+ATTR_HTML: :alt cat/spider image :title Action! :align right
|
||
[[./img/a.jpg]]
|
||
@end example
|
||
|
||
@noindent
|
||
The HTML export back-end copies the @samp{http} links from the Org file as
|
||
is.
|
||
|
||
@node Math formatting in HTML export
|
||
@subsection Math formatting in HTML export
|
||
|
||
@cindex MathJax
|
||
@cindex dvipng
|
||
@cindex dvisvgm
|
||
@cindex ImageMagick
|
||
|
||
@vindex org-html-mathjax-options~
|
||
@LaTeX{} math snippets (see @ref{@LaTeX{} fragments}) can be displayed in two
|
||
different ways on HTML pages. The default is to use the @uref{http://www.mathjax.org, MathJax},
|
||
which should work out of the box with Org@footnote{By default Org loads MathJax from @uref{https://cdnjs.com, cdnjs.com} as recommended by
|
||
@uref{http://www.mathjax.org, MathJax}.}. Some MathJax
|
||
display options can be configured via @code{org-html-mathjax-options}, or
|
||
in the buffer. For example, with the following settings,
|
||
|
||
@example
|
||
#+HTML_MATHJAX: align: left indent: 5em tagside: left font: Neo-Euler
|
||
#+HTML_MATHJAX: cancel.js noErrors.js
|
||
@end example
|
||
|
||
@noindent
|
||
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 @samp{cancel.js} and @samp{noErrors.js}@footnote{See @uref{http://docs.mathjax.org/en/latest/tex.html#tex-extensions, @TeX{} and @LaTeX{} extensions} in the @uref{http://docs.mathjax.org, MathJax manual} to learn
|
||
about extensions.}.
|
||
|
||
@vindex org-html-mathjax-template
|
||
See the docstring of @code{org-html-mathjax-options} for all supported
|
||
variables. The MathJax template can be configure via
|
||
@code{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
|
||
|
||
@example
|
||
#+OPTIONS: tex:dvipng
|
||
@end example
|
||
|
||
@example
|
||
#+OPTIONS: tex:dvisvgm
|
||
@end example
|
||
|
||
@noindent
|
||
or
|
||
|
||
@example
|
||
#+OPTIONS: tex:imagemagick
|
||
@end example
|
||
|
||
@node Text areas in HTML export
|
||
@subsection Text areas in HTML export
|
||
|
||
@cindex text areas, in HTML
|
||
Before Org mode's Babel, one popular approach to publishing code in
|
||
HTML was by using @samp{: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
|
||
@samp{#+ATTR_HTML} line as shown in the example below with the @samp{:textarea}
|
||
option. This must be followed by either an example or a source code
|
||
block. Other Org block types do not honor the @samp{: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 @samp{:width} and @samp{:height} options on the @samp{#+ATTR_HTML}
|
||
line.
|
||
|
||
@example
|
||
#+ATTR_HTML: :textarea t :width 40
|
||
#+BEGIN_EXAMPLE
|
||
(defun org-xor (a b)
|
||
"Exclusive or."
|
||
(if a (not b) b))
|
||
#+END_EXAMPLE
|
||
@end example
|
||
|
||
@node CSS support
|
||
@subsection CSS support
|
||
|
||
@cindex CSS, for HTML export
|
||
@cindex HTML export, CSS
|
||
|
||
@vindex org-export-html-todo-kwd-class-prefix
|
||
@vindex org-export-html-tag-class-prefix
|
||
You can modify the CSS style definitions for the exported file. The
|
||
HTML exporter assigns the following special CSS classes@footnote{If the classes on TODO keywords and tags lead to conflicts,
|
||
use the variables @code{org-html-todo-kwd-class-prefix} and
|
||
@code{org-html-tag-class-prefix} to make them unique.} 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.
|
||
|
||
@multitable {aaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
|
||
@item @code{p.author}
|
||
@tab author information, including email
|
||
@item @code{p.date}
|
||
@tab publishing date
|
||
@item @code{p.creator}
|
||
@tab creator info, about org mode version
|
||
@item @code{.title}
|
||
@tab document title
|
||
@item @code{.subtitle}
|
||
@tab document subtitle
|
||
@item @code{.todo}
|
||
@tab TODO keywords, all not-done states
|
||
@item @code{.done}
|
||
@tab the DONE keywords, all states that count as done
|
||
@item @code{.WAITING}
|
||
@tab each TODO keyword also uses a class named after itself
|
||
@item @code{.timestamp}
|
||
@tab timestamp
|
||
@item @code{.timestamp-kwd}
|
||
@tab keyword associated with a timestamp, like @samp{SCHEDULED}
|
||
@item @code{.timestamp-wrapper}
|
||
@tab span around keyword plus timestamp
|
||
@item @code{.tag}
|
||
@tab tag in a headline
|
||
@item @code{._HOME}
|
||
@tab each tag uses itself as a class, ``@@'' replaced by ``_''
|
||
@item @code{.target}
|
||
@tab target for links
|
||
@item @code{.linenr}
|
||
@tab the line number in a code example
|
||
@item @code{.code-highlighted}
|
||
@tab for highlighting referenced code lines
|
||
@item @code{div.outline-N}
|
||
@tab div for outline level N (headline plus text)
|
||
@item @code{div.outline-text-N}
|
||
@tab extra div for text at outline level N
|
||
@item @code{.section-number-N}
|
||
@tab section number in headlines, different for each level
|
||
@item @code{.figure-number}
|
||
@tab label like ``Figure 1:''
|
||
@item @code{.table-number}
|
||
@tab label like ``Table 1:''
|
||
@item @code{.listing-number}
|
||
@tab label like ``Listing 1:''
|
||
@item @code{div.figure}
|
||
@tab how to format an in-lined image
|
||
@item @code{pre.src}
|
||
@tab formatted source code
|
||
@item @code{pre.example}
|
||
@tab normal example
|
||
@item @code{p.verse}
|
||
@tab verse paragraph
|
||
@item @code{div.footnotes}
|
||
@tab footnote section headline
|
||
@item @code{p.footnote}
|
||
@tab footnote definition paragraph, containing a footnote
|
||
@item @code{.footref}
|
||
@tab a footnote reference number (always a <sup>)
|
||
@item @code{.footnum}
|
||
@tab footnote number in footnote definition (always <sup>)
|
||
@item @code{.org-svg}
|
||
@tab default class for a linked @samp{.svg} image
|
||
@end multitable
|
||
|
||
@vindex org-html-style-default
|
||
@vindex org-html-head
|
||
@vindex org-html-head-extra
|
||
@cindex @samp{HTML_INCLUDE_STYLE}, keyword
|
||
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.
|
||
|
||
@cindex @samp{HTML_HEAD}, keyword
|
||
@cindex @samp{HTML_HEAD_EXTRA}, keyword
|
||
@example
|
||
#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="style1.css" />
|
||
#+HTML_HEAD_EXTRA: <link rel="alternate stylesheet" type="text/css" href="style2.css" />
|
||
@end example
|
||
|
||
@vindex org-html-head-include-default-style
|
||
To just turn off the default style, customize
|
||
@code{org-html-head-include-default-style} variable, or use this option
|
||
line in the Org file.
|
||
|
||
@cindex @samp{html-style}, @samp{OPTIONS} item
|
||
@example
|
||
#+OPTIONS: html-style:nil
|
||
@end example
|
||
|
||
For longer style definitions, either use several @samp{HTML_HEAD} and
|
||
@samp{HTML_HEAD_EXTRA} keywords, or use @code{<style> ... </style>} blocks
|
||
around them. Both of these approaches can avoid referring to an
|
||
external file.
|
||
|
||
@cindex @samp{HTML_CONTAINER_CLASS}, property
|
||
In order to add styles to a sub-tree, use the @samp{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 @samp{CUSTOM_ID} property.
|
||
|
||
Never change the @code{org-html-style-default} constant. Instead use other
|
||
simpler ways of customizing as described above.
|
||
|
||
@node JavaScript support
|
||
@subsection JavaScript supported display of web pages
|
||
|
||
Sebastian Rose has written a JavaScript program especially designed to
|
||
enhance the web viewing experience of HTML files created with Org.
|
||
This program enhances large files in two different ways of viewing.
|
||
One is an @emph{Info}-like mode where each section is displayed separately
|
||
and navigation can be done with the @kbd{n} and @kbd{p}
|
||
keys, and some other keys as well, press @kbd{?} for an overview
|
||
of the available keys. The second one has a @emph{folding} view, much like
|
||
Org provides inside Emacs. The script is available at
|
||
@uref{https://orgmode.org/org-info.js} and the documentation at
|
||
@uref{https://orgmode.org/worg/code/org-info-js/}. The script is hosted on
|
||
@uref{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:
|
||
|
||
@cindex @samp{INFOJS_OPT}, keyword
|
||
@example
|
||
#+INFOJS_OPT: view:info toc:nil
|
||
@end example
|
||
|
||
@noindent
|
||
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:
|
||
|
||
@table @asis
|
||
@item @samp{path:}
|
||
The path to the script. The default is to grab the script from
|
||
@uref{https://orgmode.org/org-info.js}, but you might want to have
|
||
a local copy and use a path like @samp{../scripts/org-info.js}.
|
||
|
||
@item @samp{view:}
|
||
Initial view when the website is first shown. Possible values are:
|
||
|
||
@multitable {aaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
|
||
@item @samp{info}
|
||
@tab Info-like interface with one section per page
|
||
@item @samp{overview}
|
||
@tab Folding interface, initially showing only top-level
|
||
@item @samp{content}
|
||
@tab Folding interface, starting with all headlines visible
|
||
@item @samp{showall}
|
||
@tab Folding interface, all headlines and text visible
|
||
@end multitable
|
||
|
||
@item @samp{sdepth:}
|
||
Maximum headline level still considered as an independent section
|
||
for info and folding modes. The default is taken from
|
||
@code{org-export-headline-levels}, i.e., the @samp{H} switch in @samp{OPTIONS}.
|
||
If this is smaller than in @code{org-export-headline-levels}, each
|
||
info/folding section can still contain child headlines.
|
||
|
||
@item @samp{toc:}
|
||
Should the table of contents @emph{initially} be visible? Even when
|
||
@samp{nil}, you can always get to the ``toc'' with @kbd{i}.
|
||
|
||
@item @samp{tdepth:}
|
||
The depth of the table of contents. The defaults are taken from
|
||
the variables @code{org-export-headline-levels} and
|
||
@code{org-export-with-toc}.
|
||
|
||
@item @samp{ftoc:}
|
||
Does the CSS of the page specify a fixed position for the ``toc''?
|
||
If yes, the toc is displayed as a section.
|
||
|
||
@item @samp{ltoc:}
|
||
Should there be short contents (children) in each section? Make
|
||
this @samp{above} if the section should be above initial text.
|
||
|
||
@item @samp{mouse:}
|
||
Headings are highlighted when the mouse is over them. Should be
|
||
@samp{underline} (default) or a background color like @samp{#cccccc}.
|
||
|
||
@item @samp{buttons:}
|
||
Should view-toggle buttons be everywhere? When @samp{nil} (the
|
||
default), only one such button is present.
|
||
@end table
|
||
|
||
@noindent
|
||
@vindex org-infojs-options
|
||
@vindex org-export-html-use-infojs
|
||
You can choose default values for these options by customizing the
|
||
variable @code{org-infojs-options}. If you always want to apply the script
|
||
to your pages, configure the variable @code{org-export-html-use-infojs}.
|
||
|
||
@node @LaTeX{} Export
|
||
@section @LaTeX{} Export
|
||
|
||
@cindex @LaTeX{} export
|
||
@cindex PDF 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
|
||
@code{org-latex-compiler}; for build sequences, see
|
||
@code{org-latex-pdf-process}; for packages, see
|
||
@code{org-latex-default-packages-alist} and @code{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.
|
||
@end menu
|
||
|
||
@node @LaTeX{}/PDF export commands
|
||
@subsection @LaTeX{}/PDF export commands
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-e l l} (@code{org-latex-export-to-latex})
|
||
@kindex C-c C-e l l
|
||
@findex org-latex-export-to-latex~
|
||
Export to a @LaTeX{} file with a @samp{.tex} extension. For
|
||
@samp{myfile.org}, Org exports to @samp{myfile.tex}, overwriting without
|
||
warning.
|
||
|
||
@item @kbd{C-c C-e l L} (@code{org-latex-export-as-latex})
|
||
@kindex C-c C-e l L
|
||
@findex org-latex-export-as-latex
|
||
Export to a temporary buffer. Do not create a file.
|
||
|
||
@item @kbd{C-c C-e l p} (@code{org-latex-export-to-pdf})
|
||
@kindex C-c C-e l p
|
||
@findex org-latex-export-to-pdf
|
||
Export as @LaTeX{} file and convert it to PDF file.
|
||
|
||
@item @kbd{C-c C-e l o}
|
||
@kindex C-c C-e l o
|
||
Export as @LaTeX{} file and convert it to PDF, then open the PDF
|
||
using the default viewer.
|
||
|
||
@item @kbd{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.
|
||
@end table
|
||
|
||
@vindex org-latex-compiler
|
||
@vindex org-latex-bibtex-compiler
|
||
@vindex org-latex-default-packages-alist
|
||
@cindex pdflatex
|
||
@cindex xelatex
|
||
@cindex lualatex
|
||
@cindex @samp{LATEX_COMPILER}, keyword
|
||
The @LaTeX{} export back-end can use any of these @LaTeX{} engines:
|
||
@samp{pdflatex}, @samp{xelatex}, and @samp{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
|
||
@code{org-latex-compiler} variable or the @samp{#+LATEX_COMPILER} keyword in the
|
||
Org file. See the docstring for the
|
||
@code{org-latex-default-packages-alist} for loading packages with certain
|
||
compilers. Also see @code{org-latex-bibtex-compiler} to set the
|
||
bibliography compiler@footnote{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.}.
|
||
|
||
@node @LaTeX{} specific export settings
|
||
@subsection @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 @ref{Export Settings}).
|
||
|
||
@table @asis
|
||
@item @samp{DESCRIPTION}
|
||
@cindex @samp{DESCRIPTION}, keyword
|
||
@vindex org-latex-hyperref-template
|
||
@vindex org-latex-title-command
|
||
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
|
||
@code{org-latex-hyperref-template} for customizing metadata items.
|
||
See @code{org-latex-title-command} for typesetting description into
|
||
the document's front matter. Use multiple @samp{DESCRIPTION} keywords
|
||
for long descriptions.
|
||
|
||
@item @samp{LATEX_CLASS}
|
||
@cindex @samp{LATEX_CLASS}, keyword
|
||
@vindex org-latex-default-class
|
||
@vindex org-latex-classes
|
||
This is @LaTeX{} document class, such as @emph{article}, @emph{report},
|
||
@emph{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 @code{org-latex-default-class}
|
||
variable. Org has @emph{article} as the default class. A valid
|
||
default class must be an element of @code{org-latex-classes}.
|
||
|
||
@item @samp{LATEX_CLASS_OPTIONS}
|
||
@cindex @samp{LATEX_CLASS_OPTIONS}, keyword
|
||
Options the @LaTeX{} export back-end uses when calling the @LaTeX{}
|
||
document class.
|
||
|
||
@item @samp{LATEX_COMPILER}
|
||
@cindex @samp{LATEX_COMPILER}, keyword
|
||
@vindex org-latex-compiler
|
||
The compiler, such as @samp{pdflatex}, @samp{xelatex}, @samp{lualatex}, for
|
||
producing the PDF. See @code{org-latex-compiler}.
|
||
|
||
@item @samp{LATEX_HEADER}
|
||
@itemx @samp{LATEX_HEADER_EXTRA}
|
||
@cindex @samp{LATEX_HEADER}, keyword
|
||
@cindex @samp{LATEX_HEADER_EXTRA}, keyword
|
||
@vindex org-latex-classes
|
||
Arbitrary lines to add to the document's preamble, before the
|
||
hyperref settings. See @code{org-latex-classes} for adjusting the
|
||
structure and order of the @LaTeX{} headers.
|
||
|
||
@item @samp{KEYWORDS}
|
||
@cindex @samp{KEYWORDS}, keyword
|
||
@vindex org-latex-hyperref-template
|
||
@vindex org-latex-title-command
|
||
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
|
||
@code{org-latex-hyperref-template} for customizing metadata items.
|
||
See @code{org-latex-title-command} for typesetting description into
|
||
the document's front matter. Use multiple @samp{KEYWORDS} lines if
|
||
necessary.
|
||
|
||
@item @samp{SUBTITLE}
|
||
@cindex @samp{SUBTITLE}, keyword
|
||
@vindex org-latex-subtitle-separate
|
||
@vindex org-latex-subtitle-format
|
||
The document's subtitle. It is typeset as per
|
||
@code{org-latex-subtitle-format}. If @code{org-latex-subtitle-separate} is
|
||
non-@code{nil}, it is typed as part of the @code{\title} macro. See
|
||
@code{org-latex-hyperref-template} for customizing metadata items.
|
||
See @code{org-latex-title-command} for typesetting description
|
||
into the document's front matter.
|
||
@end table
|
||
|
||
The following sections have further details.
|
||
|
||
@node @LaTeX{} header and sectioning
|
||
@subsection @LaTeX{} header and sectioning structure
|
||
|
||
@cindex @LaTeX{} class
|
||
@cindex @LaTeX{} sectioning structure
|
||
@cindex @LaTeX{} header
|
||
@cindex header, for @LaTeX{} files
|
||
@cindex sectioning structure, for @LaTeX{} export
|
||
|
||
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 @ref{Export Settings}).
|
||
|
||
By default, the @LaTeX{} export back-end uses the @emph{article} class.
|
||
|
||
@vindex org-latex-default-class
|
||
@vindex org-latex-classes
|
||
@vindex org-latex-default-packages-alist
|
||
@vindex org-latex-packages-alist
|
||
To change the default class globally, edit @code{org-latex-default-class}.
|
||
To change the default class locally in an Org file, add option lines
|
||
@samp{#+LATEX_CLASS: myclass}. To change the default class for just a part
|
||
of the Org file, set a sub-tree property, @samp{EXPORT_LATEX_CLASS}. The
|
||
class name entered here must be valid member of @code{org-latex-classes}.
|
||
This variable defines a header template for each class into which the
|
||
exporter splices the values of @code{org-latex-default-packages-alist} and
|
||
@code{org-latex-packages-alist}. Use the same three variables to define
|
||
custom sectioning or custom classes.
|
||
|
||
@cindex @samp{LATEX_CLASS}, keyword
|
||
@cindex @samp{LATEX_CLASS_OPTIONS}, keyword
|
||
@cindex @samp{EXPORT_LATEX_CLASS}, property
|
||
@cindex @samp{EXPORT_LATEX_CLASS_OPTIONS}, property
|
||
The @LaTeX{} export back-end sends the @samp{LATEX_CLASS_OPTIONS} keyword and
|
||
@samp{EXPORT_LATEX_CLASS_OPTIONS} property as options to the @LaTeX{}
|
||
@code{\documentclass} macro. The options and the syntax for specifying
|
||
them, including enclosing them in square brackets, follow @LaTeX{}
|
||
conventions.
|
||
|
||
@example
|
||
#+LATEX_CLASS_OPTIONS: [a4paper,11pt,twoside,twocolumn]
|
||
@end example
|
||
|
||
@cindex @samp{LATEX_HEADER}, keyword
|
||
@cindex @samp{LATEX_HEADER_EXTRA}, keyword
|
||
The @LaTeX{} export back-end appends values from @samp{LATEX_HEADER} and
|
||
@samp{LATEX_HEADER_EXTRA} keywords to the @LaTeX{} header. The docstring for
|
||
@code{org-latex-classes} explains in more detail. Also note that @LaTeX{}
|
||
export back-end does not append @samp{LATEX_HEADER_EXTRA} to the header
|
||
when previewing @LaTeX{} snippets (see @ref{Previewing @LaTeX{} fragments}).
|
||
|
||
A sample Org file with the above headers:
|
||
|
||
@example
|
||
#+LATEX_CLASS: article
|
||
#+LATEX_CLASS_OPTIONS: [a4paper]
|
||
#+LATEX_HEADER: \usepackage@{xyz@}
|
||
|
||
* Headline 1
|
||
some text
|
||
* Headline 2
|
||
some more text
|
||
@end example
|
||
|
||
@node Quoting @LaTeX{} code
|
||
@subsection Quoting @LaTeX{} code
|
||
|
||
The @LaTeX{} export back-end can insert any arbitrary @LaTeX{} code, see
|
||
@ref{Embedded @LaTeX{}}. There are three ways to embed such code in the Org
|
||
file and they all use different quoting syntax.
|
||
|
||
@cindex inline, in @LaTeX{} export
|
||
Inserting in-line quoted with @@ symbols:
|
||
|
||
@example
|
||
Code embedded in-line @@@@latex:any arbitrary LaTeX code@@@@ in a paragraph.
|
||
@end example
|
||
|
||
@cindex @samp{LATEX}, keyword
|
||
Inserting as one or more keyword lines in the Org file:
|
||
|
||
@example
|
||
#+LATEX: any arbitrary LaTeX code
|
||
@end example
|
||
|
||
@cindex @samp{BEGIN_EXPORT latex}
|
||
Inserting as an export block in the Org file, where the back-end
|
||
exports any code between begin and end markers:
|
||
|
||
@example
|
||
#+BEGIN_EXPORT latex
|
||
any arbitrary LaTeX code
|
||
#+END_EXPORT
|
||
@end example
|
||
|
||
@node Tables in @LaTeX{} export
|
||
@subsection Tables in @LaTeX{} export
|
||
|
||
@cindex tables, in @LaTeX{} export
|
||
|
||
The @LaTeX{} export back-end can pass several @LaTeX{} attributes for table
|
||
contents and layout. Besides specifying label and caption (see
|
||
@ref{Images and Tables}), the other valid @LaTeX{} attributes include:
|
||
|
||
@table @asis
|
||
@item @samp{:mode}
|
||
@vindex org-latex-default-table-mode
|
||
The @LaTeX{} export back-end wraps the table differently depending
|
||
on the mode for accurate rendering of math symbols. Mode is
|
||
either @samp{table}, @samp{math}, @samp{inline-math} or @samp{verbatim}.
|
||
|
||
For @samp{math} or @samp{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 @code{org-latex-default-table-mode}. The @LaTeX{} export back-end
|
||
merges contiguous tables in the same mode into a single
|
||
environment.
|
||
|
||
@item @samp{:environment}
|
||
@vindex org-latex-default-table-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
|
||
@code{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
|
||
@code{org-latex-packages-alist} variable for configuring these
|
||
packages for @LaTeX{} snippet previews, if any.
|
||
|
||
@item @samp{:caption}
|
||
Use @samp{CAPTION} keyword to set a simple caption for a table (see
|
||
@ref{Images and Tables}). For custom captions, use @samp{:caption}
|
||
attribute, which accepts raw @LaTeX{} code. @samp{:caption} value
|
||
overrides @samp{CAPTION} value.
|
||
|
||
@item @samp{:float}
|
||
@itemx @samp{:placement}
|
||
The table environments by default are not floats in @LaTeX{}. To
|
||
make them floating objects use @samp{:float} with one of the following
|
||
options: @samp{sideways}, @samp{multicolumn}, @samp{t}, and @samp{nil}.
|
||
|
||
@LaTeX{} floats can also have additional layout @samp{:placement}
|
||
attributes. These are the usual @samp{[h t b p ! H]} permissions
|
||
specified in square brackets. Note that for @samp{:float sideways}
|
||
tables, the @LaTeX{} export back-end ignores @samp{:placement}
|
||
attributes.
|
||
|
||
@item @samp{:align}
|
||
@itemx @samp{:font}
|
||
@itemx @samp{:width}
|
||
The @LaTeX{} export back-end uses these attributes for regular
|
||
tables to set their alignments, fonts, and widths.
|
||
|
||
@item @samp{:spread}
|
||
When @samp{:spread} is non-@code{nil}, the @LaTeX{} export back-end spreads or
|
||
shrinks the table by the @samp{:width} for tabu and longtabu
|
||
environments. @samp{:spread} has no effect if @samp{:width} is not set.
|
||
|
||
@item @samp{:booktabs}
|
||
@itemx @samp{:center}
|
||
@itemx @samp{:rmlines}
|
||
@vindex org-latex-tables-booktabs
|
||
@vindex org-latex-tables-centered
|
||
All three commands are toggles. @samp{:booktabs} brings in modern
|
||
typesetting enhancements to regular tables. The booktabs package
|
||
has to be loaded through @code{org-latex-packages-alist}. @samp{:center}
|
||
is for centering the table. @samp{:rmlines} removes all but the very
|
||
first horizontal line made of ASCII characters from ``table.el''
|
||
tables only.
|
||
|
||
@item @samp{:math-prefix}
|
||
@itemx @samp{:math-suffix}
|
||
@itemx @samp{:math-arguments}
|
||
The @LaTeX{} export back-end inserts @samp{:math-prefix} string value in
|
||
a math environment before the table. The @LaTeX{} export back-end
|
||
inserts @samp{:math-suffix} string value in a math environment after
|
||
the table. The @LaTeX{} export back-end inserts @samp{:math-arguments}
|
||
string value between the macro name and the table's contents.
|
||
@samp{:math-arguments} comes in use for matrix macros that require
|
||
more than one argument, such as @samp{qbordermatrix}.
|
||
@end table
|
||
|
||
@LaTeX{} table attributes help formatting tables for a wide range of
|
||
situations, such as matrix product or spanning multiple pages:
|
||
|
||
@example
|
||
#+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 |
|
||
@end example
|
||
|
||
Set the caption with the @LaTeX{} command
|
||
@samp{\bicaption@{HeadingA@}@{HeadingB@}}:
|
||
|
||
@example
|
||
#+ATTR_LATEX: :caption \bicaption@{HeadingA@}@{HeadingB@}
|
||
| ... | ... |
|
||
| ... | ... |
|
||
@end example
|
||
|
||
@node Images in @LaTeX{} export
|
||
@subsection Images in @LaTeX{} export
|
||
|
||
@cindex images, inline in LaTeX
|
||
@cindex inlining images in LaTeX
|
||
@cindex @samp{ATTR_LATEX}, keyword
|
||
|
||
The @LaTeX{} export back-end processes image links in Org files that do
|
||
not have descriptions, such as these links @samp{[[file:img.jpg]]} or
|
||
@samp{[[./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 @samp{\includegraphics} macro to
|
||
insert the image. But for TikZ (@uref{http://sourceforge.net/projects/pgf/})
|
||
images, the back-end uses an @code{\input} macro wrapped within
|
||
a @code{tikzpicture} environment.
|
||
|
||
For specifying image @samp{:width}, @samp{:height}, and other @samp{:options}, use
|
||
this syntax:
|
||
|
||
@example
|
||
#+ATTR_LATEX: :width 5cm :options angle=90
|
||
[[./img/sed-hr4049.pdf]]
|
||
@end example
|
||
|
||
For custom commands for captions, use the @samp{:caption} attribute. It
|
||
overrides the default @samp{#+CAPTION} value:
|
||
|
||
@example
|
||
#+ATTR_LATEX: :caption \bicaption@{HeadingA@}@{HeadingB@}
|
||
[[./img/sed-hr4049.pdf]]
|
||
@end example
|
||
|
||
When captions follow the method as described in @ref{Images and Tables},
|
||
the @LaTeX{} export back-end wraps the picture in a floating @samp{figure}
|
||
environment. To float an image without specifying a caption, set the
|
||
@samp{:float} attribute to one of the following:
|
||
|
||
@table @asis
|
||
@item @samp{t}
|
||
For a standard @samp{figure} environment; used by default whenever an
|
||
image has a caption.
|
||
|
||
@item @samp{multicolumn}
|
||
To span the image across multiple columns of a page; the back-end
|
||
wraps the image in a @samp{figure*} environment.
|
||
|
||
@item @samp{wrap}
|
||
For text to flow around the image on the right; the figure
|
||
occupies the left half of the page.
|
||
|
||
@item @samp{sideways}
|
||
For a new page with the image sideways, rotated ninety degrees,
|
||
in a @samp{sidewaysfigure} environment; overrides @samp{:placement}
|
||
setting.
|
||
|
||
@item @samp{nil}
|
||
To avoid a @samp{:float} even if using a caption.
|
||
@end table
|
||
|
||
@noindent
|
||
Use the @samp{placement} attribute to modify a floating environment's
|
||
placement.
|
||
|
||
@example
|
||
#+ATTR_LATEX: :float wrap :width 0.38\textwidth :placement @{r@}@{0.4\textwidth@}
|
||
[[./img/hst.png]]
|
||
@end example
|
||
|
||
@vindex org-latex-images-centered
|
||
@cindex center image in LaTeX export
|
||
@cindex image, centering in LaTeX export
|
||
The @LaTeX{} export back-end centers all images by default. Setting
|
||
@samp{:center} to @samp{nil} disables centering. To disable centering globally,
|
||
set @code{org-latex-images-centered} to @samp{t}.
|
||
|
||
Set the @samp{:comment-include} attribute to non-@code{nil} value for the @LaTeX{}
|
||
export back-end to comment out the @samp{\includegraphics} macro.
|
||
|
||
@node Plain lists in @LaTeX{} export
|
||
@subsection Plain lists in @LaTeX{} export
|
||
|
||
@cindex plain lists, in @LaTeX{} export
|
||
@cindex @samp{ATTR_LATEX}, keyword
|
||
The @LaTeX{} export back-end accepts the @samp{environment} and @samp{options}
|
||
attributes for plain lists. Both attributes work together for
|
||
customizing lists, as shown in the examples:
|
||
|
||
@example
|
||
#+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.
|
||
@end example
|
||
|
||
Since @LaTeX{} supports only four levels of nesting for lists, use an
|
||
external package, such as @samp{enumitem} in @LaTeX{}, for levels deeper than
|
||
four:
|
||
|
||
@example
|
||
#+LATEX_HEADER: \usepackage@{enumitem@}
|
||
#+LATEX_HEADER: \renewlist@{itemize@}@{itemize@}@{9@}
|
||
#+LATEX_HEADER: \setlist[itemize]@{label=$\circ$@}
|
||
- One
|
||
- Two
|
||
- Three
|
||
- Four
|
||
- Five
|
||
@end example
|
||
|
||
@node Source blocks in @LaTeX{} export
|
||
@subsection Source blocks in @LaTeX{} export
|
||
|
||
@cindex source blocks, in @LaTeX{} export
|
||
@cindex @samp{ATTR_LATEX}, keyword
|
||
|
||
The @LaTeX{} export back-end can make source code blocks into floating
|
||
objects through the attributes @samp{:float} and @samp{:options}. For @samp{:float}:
|
||
|
||
@table @asis
|
||
@item @samp{t}
|
||
Makes a source block float; by default floats any source block
|
||
with a caption.
|
||
|
||
@item @samp{multicolumn}
|
||
Spans the source block across multiple columns of a page.
|
||
|
||
@item @samp{nil}
|
||
Avoids a @samp{:float} even if using a caption; useful for source code
|
||
blocks that may not fit on a page.
|
||
@end table
|
||
|
||
@example
|
||
#+ATTR_LATEX: :float nil
|
||
#+BEGIN_SRC emacs-lisp
|
||
Lisp code that may not fit in a single page.
|
||
#+END_SRC
|
||
@end example
|
||
|
||
@vindex org-latex-listings-options
|
||
@vindex org-latex-minted-options
|
||
The @LaTeX{} export back-end passes string values in @samp{:options} to @LaTeX{}
|
||
packages for customization of that specific source block. In the
|
||
example below, the @samp{:options} are set for Minted. Minted is a source
|
||
code highlighting @LaTeX{} package with many configurable options.
|
||
|
||
@example
|
||
#+ATTR_LATEX: :options commentstyle=\bfseries
|
||
#+BEGIN_SRC emacs-lisp
|
||
(defun Fib (n)
|
||
(if (< n 2) n (+ (Fib (- n 1)) (Fib (- n 2)))))
|
||
#+END_SRC
|
||
@end example
|
||
|
||
To apply similar configuration options for all source blocks in
|
||
a file, use the @code{org-latex-listings-options} and
|
||
@code{org-latex-minted-options} variables.
|
||
|
||
@node Example blocks in @LaTeX{} export
|
||
@subsection Example blocks in @LaTeX{} export
|
||
|
||
@cindex example blocks, in @LaTeX{} export
|
||
@cindex verbatim blocks, in @LaTeX{} export
|
||
@cindex @samp{ATTR_LATEX}, keyword
|
||
|
||
The @LaTeX{} export back-end wraps the contents of example blocks in
|
||
a @samp{verbatim} environment. To change this behavior to use another
|
||
environment globally, specify an appropriate export filter (see
|
||
@ref{Advanced Configuration}). To change this behavior to use another
|
||
environment for each block, use the @samp{:environment} parameter to
|
||
specify a custom environment.
|
||
|
||
@example
|
||
#+ATTR_LATEX: :environment myverbatim
|
||
#+BEGIN_EXAMPLE
|
||
This sentence is false.
|
||
#+END_EXAMPLE
|
||
@end example
|
||
|
||
@node Special blocks in @LaTeX{} export
|
||
@subsection Special blocks in @LaTeX{} export
|
||
|
||
@cindex special blocks, in @LaTeX{} export
|
||
@cindex abstract, in @LaTeX{} export
|
||
@cindex proof, in @LaTeX{} export
|
||
@cindex @samp{ATTR_LATEX}, keyword
|
||
|
||
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
|
||
@samp{:options}, if any, and appends as-is to that environment's opening
|
||
string. For example:
|
||
|
||
@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
|
||
@end example
|
||
|
||
@noindent
|
||
exports to
|
||
|
||
@example
|
||
\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@}
|
||
@end example
|
||
|
||
If you need to insert a specific caption command, use @samp{:caption}
|
||
attribute. It overrides standard @samp{CAPTION} value, if any. For
|
||
example:
|
||
|
||
@example
|
||
#+ATTR_LATEX: :caption \MyCaption@{HeadingA@}
|
||
#+BEGIN_proof
|
||
...
|
||
#+END_proof
|
||
@end example
|
||
|
||
@node Horizontal rules in @LaTeX{} export
|
||
@subsection Horizontal rules in @LaTeX{} export
|
||
|
||
@cindex horizontal rules, in @LaTeX{} export
|
||
@cindex @samp{ATTR_LATEX}, keyword
|
||
|
||
The @LaTeX{} export back-end converts horizontal rules by the specified
|
||
@samp{:width} and @samp{:thickness} attributes. For example:
|
||
|
||
@example
|
||
#+ATTR_LATEX: :width .6\textwidth :thickness 0.8pt
|
||
-----
|
||
@end example
|
||
|
||
@node Markdown Export
|
||
@section Markdown Export
|
||
|
||
@cindex Markdown export
|
||
|
||
The Markdown export back-end, ``md'', converts an Org file to a Markdown
|
||
format, as defined at @uref{http://daringfireball.net/projects/markdown/}.
|
||
|
||
Since ``md'' is built on top of the HTML back-end, any Org constructs
|
||
not supported by Markdown, such as tables, the underlying ``html''
|
||
back-end (see @ref{HTML Export}) converts them.
|
||
|
||
@anchor{Markdown export commands}
|
||
@subheading Markdown export commands
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-e m m} (@code{org-md-export-to-markdown})
|
||
@kindex C-c C-c m m
|
||
@findex org-md-export-to-markdown
|
||
Export to a text file with Markdown syntax. For @samp{myfile.org},
|
||
Org exports to @samp{myfile.md}, overwritten without warning.
|
||
|
||
@item @kbd{C-c C-e m M} (@code{org-md-export-as-markdown})
|
||
@kindex C-c C-c m M
|
||
@findex org-md-export-as-markdown
|
||
Export to a temporary buffer. Does not create a file.
|
||
|
||
@item @kbd{C-c C-e m o}
|
||
@kindex C-c C-e m o
|
||
Export as a text file with Markdown syntax, then open it.
|
||
@end table
|
||
|
||
@anchor{Header and sectioning structure (1)}
|
||
@subheading Header and sectioning structure
|
||
|
||
@vindex org-md-headline-style
|
||
Based on @code{org-md-headline-style}, Markdown export can generate
|
||
headlines of both @emph{atx} and @emph{setext} types. @emph{atx} limits headline
|
||
levels to two whereas @emph{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 @ref{Export Settings}).
|
||
|
||
@node OpenDocument Text Export
|
||
@section OpenDocument Text Export
|
||
|
||
@cindex ODT
|
||
@cindex OpenDocument
|
||
@cindex export, OpenDocument
|
||
@cindex LibreOffice
|
||
|
||
The ODT export back-end handles creating of OpenDocument Text (ODT)
|
||
format. Documents created by this exporter use the
|
||
@cite{OpenDocument-v1.2 specification}@footnote{See @uref{http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html, Open Document Format for Office Applications
|
||
(OpenDocument) Version 1.2}.} 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.
|
||
@end menu
|
||
|
||
@node Pre-requisites for ODT export
|
||
@subsection Pre-requisites for ODT export
|
||
|
||
@cindex zip
|
||
|
||
The ODT export back-end relies on the zip program to create the final
|
||
compressed ODT output. Check if @samp{zip} is locally available and
|
||
executable. Without it, export cannot finish.
|
||
|
||
@node ODT export commands
|
||
@subsection ODT export commands
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-e o o} (@code{org-export-to-odt})
|
||
@kindex C-c C-e o o
|
||
@findex org-export-to-odt
|
||
Export as OpenDocument Text file.
|
||
|
||
@cindex @samp{EXPORT_FILE_NAME}, property
|
||
@vindex org-odt-preferred-output-format
|
||
|
||
If @code{org-odt-preferred-output-format} is specified, the ODT export
|
||
back-end automatically converts the exported file to that format.
|
||
|
||
For @samp{myfile.org}, Org exports to @samp{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, @kbd{C-c @@} selects the current sub-tree. If the tree head entry has,
|
||
or inherits, an @samp{EXPORT_FILE_NAME} property, the ODT export
|
||
back-end uses that for file name.
|
||
|
||
@item @kbd{C-c C-e o O}
|
||
@kindex C-c C-e o O
|
||
Export as an OpenDocument Text file and open the resulting file.
|
||
|
||
@vindex org-export-odt-preferred-output-format
|
||
If @code{org-export-odt-preferred-output-format} is specified, open
|
||
the converted file instead. See @ref{Automatically exporting to other formats}.
|
||
@end table
|
||
|
||
@node ODT specific export settings
|
||
@subsection 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 @ref{Export Settings}).
|
||
|
||
@table @asis
|
||
@item @samp{DESCRIPTION}
|
||
@cindex @samp{DESCRIPTION}, keyword
|
||
This is the document's description, which the ODT export back-end
|
||
inserts as document metadata. For long descriptions, use
|
||
multiple lines, prefixed with @samp{DESCRIPTION}.
|
||
|
||
@item @samp{KEYWORDS}
|
||
@cindex @samp{KEYWORDS}, keyword
|
||
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
|
||
@samp{KEYWORDS} if necessary.
|
||
|
||
@item @samp{ODT_STYLES_FILE}
|
||
@cindex @samp{ODT_STYLES_FILE}, keyword
|
||
@vindex org-odt-styles-file
|
||
The ODT export back-end uses the @code{org-odt-styles-file} by
|
||
default. See @ref{Applying custom styles} for details.
|
||
|
||
@item @samp{SUBTITLE}
|
||
@cindex @samp{SUBTITLE}, keyword
|
||
The document subtitle.
|
||
@end table
|
||
|
||
@node Extending ODT export
|
||
@subsection 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 @samp{doc}, or
|
||
convert a document from one format, say @samp{csv}, to another format, say
|
||
@samp{xls}.
|
||
|
||
@cindex @file{unoconv}
|
||
@vindex org-odt-convert-process
|
||
Customize @code{org-odt-convert-process} variable to point to @samp{unoconv},
|
||
which is the ODT's preferred converter. Working installations of
|
||
LibreOffice would already have @samp{unoconv} installed. Alternatively,
|
||
other converters may be substituted here. See @ref{Configuring a document converter}.
|
||
|
||
@anchor{Automatically exporting to other formats}
|
||
@subsubheading Automatically exporting to other formats
|
||
|
||
@vindex org-odt-preferred-output-format
|
||
If ODT format is just an intermediate step to get to other formats,
|
||
such as @samp{doc}, @samp{docx}, @samp{rtf}, or @samp{pdf}, etc., then extend the ODT
|
||
export back-end to directly produce that format. Specify the final
|
||
format in the @code{org-odt-preferred-output-format} variable. This is one
|
||
way to extend (see @ref{ODT export commands}).
|
||
|
||
@anchor{Converting between document formats}
|
||
@subsubheading 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:
|
||
|
||
@table @asis
|
||
@item @kbd{M-x org-odt-convert}
|
||
@findex org-odt-convert
|
||
Convert an existing document from one format to another. With
|
||
a prefix argument, opens the newly produced file.
|
||
@end table
|
||
|
||
@node Applying custom styles
|
||
@subsection Applying custom styles
|
||
|
||
@cindex styles, custom
|
||
@cindex template, custom
|
||
|
||
The ODT export back-end comes with many OpenDocument styles (see
|
||
@ref{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.
|
||
|
||
@anchor{Applying custom styles the easy way}
|
||
@subsubheading Applying custom styles: the easy way
|
||
|
||
@enumerate
|
||
@item
|
||
Create a sample @samp{example.org} file with settings as shown below,
|
||
and export it to ODT format.
|
||
|
||
@example
|
||
#+OPTIONS: H:10 num:t
|
||
@end example
|
||
|
||
@item
|
||
Open the above @samp{example.odt} using LibreOffice. Use the @emph{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.
|
||
|
||
@item
|
||
@vindex org-odt-styles-file
|
||
Customize the variable @code{org-odt-styles-file} and point it to the
|
||
newly created file. For additional configuration options, see
|
||
@ref{x-overriding-factory-styles, , Overriding factory styles}.
|
||
|
||
@cindex @samp{ODT_STYLES_FILE}, keyword
|
||
To apply an ODT style to a particular file, use the
|
||
@samp{ODT_STYLES_FILE} keyword as shown in the example below:
|
||
|
||
@example
|
||
#+ODT_STYLES_FILE: "/path/to/example.ott"
|
||
@end example
|
||
|
||
@noindent
|
||
or
|
||
|
||
@example
|
||
#+ODT_STYLES_FILE: ("/path/to/file.ott" ("styles.xml" "image/hdr.png"))
|
||
@end example
|
||
@end enumerate
|
||
|
||
@anchor{Using third-party styles and templates}
|
||
@subsubheading 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.
|
||
|
||
@node Links in ODT export
|
||
@subsection Links in ODT export
|
||
|
||
@cindex 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 @samp{\ref@{label@}}-style reference to an image, table etc., is replaced
|
||
with a cross-reference and sequence number of the labeled entity. See
|
||
@ref{Labels and captions in ODT export}.
|
||
|
||
@node Tables in ODT export
|
||
@subsection Tables in ODT export
|
||
|
||
@cindex tables, in ODT export
|
||
|
||
The ODT export back-end handles native Org mode tables (see @ref{Tables})
|
||
and simple @samp{table.el} tables. Complex @samp{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 @ref{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 @ref{Column Width and Alignment}).
|
||
|
||
Note that the ODT export back-end interprets column widths as weighted
|
||
ratios, the default weight being 1.
|
||
|
||
@cindex @samp{ATTR_ODT}, keyword
|
||
Specifying @samp{:rel-width} property on an @samp{ATTR_ODT} line controls the
|
||
width of the table. For example:
|
||
|
||
@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 |
|
||
@end example
|
||
|
||
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 @samp{ATTR_ODT} keyword. See @ref{Customizing tables in ODT export}.
|
||
|
||
@node Images in ODT export
|
||
@subsection Images in ODT export
|
||
|
||
@cindex images, embedding in ODT
|
||
@cindex embedding images in ODT
|
||
|
||
@anchor{Embedding images}
|
||
@subsubheading Embedding images
|
||
|
||
The ODT export back-end processes image links in Org files that do not
|
||
have descriptions, such as these links @samp{[[file:img.jpg]]} or @samp{[[./img.jpg]]},
|
||
as direct image insertions in the final output. Either of these
|
||
examples works:
|
||
|
||
@example
|
||
[[file:img.png]]
|
||
@end example
|
||
|
||
@example
|
||
[[./img.png]]
|
||
@end example
|
||
|
||
@anchor{Embedding clickable images}
|
||
@subsubheading Embedding clickable images
|
||
|
||
For clickable images, provide a link whose description is another link
|
||
to an image file. For example, to embed an image
|
||
@samp{org-mode-unicorn.png} which when clicked jumps to @uref{https://orgmode.org}
|
||
website, do the following
|
||
|
||
@example
|
||
[[https://orgmode.org][./org-mode-unicorn.png]]
|
||
@end example
|
||
|
||
@anchor{Sizing and scaling of embedded images}
|
||
@subsubheading Sizing and scaling of embedded images
|
||
|
||
@cindex @samp{ATTR_ODT}, keyword
|
||
|
||
Control the size and scale of the embedded images with the @samp{ATTR_ODT}
|
||
attribute.
|
||
|
||
@cindex identify, ImageMagick
|
||
@vindex org-odt-pixels-per-inch
|
||
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 @code{create-image} and
|
||
@code{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 @code{org-odt-pixels-per-inch} into the familiar 72
|
||
dpi or 96 dpi. The default value for this is in
|
||
@code{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:
|
||
|
||
@table @asis
|
||
@item Explicitly size the image
|
||
To embed @samp{img.png} as a 10 cm x 10 cm image, do the following:
|
||
|
||
@example
|
||
#+ATTR_ODT: :width 10 :height 10
|
||
[[./img.png]]
|
||
@end example
|
||
|
||
@item Scale the image
|
||
To embed @samp{img.png} at half its size, do the following:
|
||
|
||
@example
|
||
#+ATTR_ODT: :scale 0.5
|
||
[[./img.png]]
|
||
@end example
|
||
|
||
@item Scale the image to a specific width
|
||
To embed @samp{img.png} with a width of 10 cm while retaining the
|
||
original height:width ratio, do the following:
|
||
|
||
@example
|
||
#+ATTR_ODT: :width 10
|
||
[[./img.png]]
|
||
@end example
|
||
|
||
@item Scale the image to a specific height
|
||
To embed @samp{img.png} with a height of 10 cm while retaining the
|
||
original height:width ratio, do the following:
|
||
|
||
@example
|
||
#+ATTR_ODT: :height 10
|
||
[[./img.png]]
|
||
@end example
|
||
@end table
|
||
|
||
@anchor{Anchoring of images}
|
||
@subsubheading Anchoring of images
|
||
|
||
@cindex @samp{ATTR_ODT}, keyword
|
||
The ODT export back-end can anchor images to @samp{"as-char"},
|
||
@samp{"paragraph"}, or @samp{"page"}. Set the preferred anchor using the
|
||
@samp{:anchor} property of the @samp{ATTR_ODT} line.
|
||
|
||
To create an image that is anchored to a page:
|
||
|
||
@example
|
||
#+ATTR_ODT: :anchor "page"
|
||
[[./img.png]]
|
||
@end example
|
||
|
||
@node Math formatting in ODT export
|
||
@subsection 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.
|
||
@end menu
|
||
|
||
@node @LaTeX{} math snippets
|
||
@subsubsection @LaTeX{} math snippets
|
||
|
||
@LaTeX{} math snippets (see @ref{@LaTeX{} fragments}) can be embedded in the ODT
|
||
document in one of the following ways:
|
||
|
||
@table @asis
|
||
@item MathML
|
||
@cindex MathML
|
||
Add this line to the Org file. This option is activated on
|
||
a per-file basis.
|
||
|
||
@example
|
||
#+OPTIONS: tex:t
|
||
@end example
|
||
|
||
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.
|
||
|
||
@vindex org-latex-to-mathml-convert-command
|
||
@vindex org-latex-to-mathml-jar-file
|
||
You can specify the @LaTeX{}-to-MathML converter by customizing the
|
||
variables @code{org-latex-to-mathml-convert-command} and
|
||
@code{org-latex-to-mathml-jar-file}.
|
||
|
||
If you prefer to use MathToWeb@footnote{See @uref{http://www.mathtoweb.com/cgi-bin/mathtoweb_home.pl, MathToWeb}.} as your converter, you can
|
||
configure the above variables as shown below.
|
||
|
||
@lisp
|
||
(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")
|
||
@end lisp
|
||
|
||
To use @LaTeX{}ML@footnote{See @uref{http://dlmf.nist.gov/LaTeXML/}.} use
|
||
|
||
@lisp
|
||
(setq org-latex-to-mathml-convert-command
|
||
"latexmlmath \"%i\" --presentationmathml=%o")
|
||
@end lisp
|
||
|
||
To quickly verify the reliability of the @LaTeX{}-to-MathML
|
||
converter, use the following commands:
|
||
|
||
@table @asis
|
||
@item @kbd{M-x org-export-as-odf}
|
||
Convert a @LaTeX{} math snippet to an OpenDocument formula
|
||
(@samp{.odf}) file.
|
||
|
||
@item @kbd{M-x org-export-as-odf-and-open}
|
||
Convert a @LaTeX{} math snippet to an OpenDocument formula
|
||
(@samp{.odf}) file and open the formula file with the
|
||
system-registered application.
|
||
@end table
|
||
|
||
@item PNG images
|
||
@cindex dvipng
|
||
@cindex dvisvgm
|
||
@cindex ImageMagick
|
||
Add this line to the Org file. This option is activated on
|
||
a per-file basis.
|
||
|
||
@example
|
||
#+OPTIONS: tex:dvipng
|
||
@end example
|
||
|
||
@example
|
||
#+OPTIONS: tex:dvisvgm
|
||
@end example
|
||
|
||
@noindent
|
||
or
|
||
|
||
@example
|
||
#+OPTIONS: tex:imagemagick
|
||
@end example
|
||
|
||
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.
|
||
@end table
|
||
|
||
@node MathML and OpenDocument formula files
|
||
@subsubsection 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 (@samp{.mml}) source or its OpenDocument formula (@samp{.odf}) file as
|
||
shown below:
|
||
|
||
@example
|
||
[[./equation.mml]]
|
||
@end example
|
||
|
||
@noindent
|
||
or
|
||
|
||
@example
|
||
[[./equation.odf]]
|
||
@end example
|
||
|
||
@node Labels and captions in ODT export
|
||
@subsection 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.
|
||
|
||
@example
|
||
#+CAPTION: Bell curve
|
||
#+NAME: fig:SED-HR4049
|
||
[[./img/a.png]]
|
||
@end example
|
||
|
||
When rendered, it may show as follows in the exported document:
|
||
|
||
@example
|
||
Figure 2: Bell curve
|
||
@end example
|
||
|
||
@vindex org-odt-category-map-alist
|
||
To modify the category component of the caption, customize the option
|
||
@code{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:
|
||
|
||
@lisp
|
||
(setq org-odt-category-map-alist
|
||
'(("__Figure__" "Illustration" "value" "Figure" org-odt--enumerable-image-p)))
|
||
@end lisp
|
||
|
||
With the above modification, the previous example changes to:
|
||
|
||
@example
|
||
Illustration 2: Bell curve
|
||
@end example
|
||
|
||
@node Literal examples in ODT export
|
||
@subsection Literal examples in ODT export
|
||
|
||
The ODT export back-end supports literal examples (see @ref{Literal Examples}) with full fontification. Internally, the ODT export
|
||
back-end relies on @samp{htmlfontify.el} to generate the style definitions
|
||
needed for fancy listings. The auto-generated styles get @samp{OrgSrc}
|
||
prefix and inherit colors from the faces used by Emacs Font Lock
|
||
library for that source language.
|
||
|
||
@vindex org-odt-fontify-srcblocks
|
||
For custom fontification styles, customize the
|
||
@code{org-odt-create-custom-styles-for-srcblocks} option.
|
||
|
||
@vindex org-odt-create-custom-styles-for-srcblocks
|
||
To turn off fontification of literal examples, customize the
|
||
@code{org-odt-fontify-srcblocks} option.
|
||
|
||
@node Advanced topics in ODT export
|
||
@subsection Advanced topics in ODT export
|
||
|
||
The ODT export back-end has extensive features useful for power users
|
||
and frequent uses of ODT formats.
|
||
|
||
@anchor{Configuring a document converter}
|
||
@subsubheading Configuring a document converter
|
||
|
||
@cindex convert
|
||
@cindex doc, docx, rtf
|
||
@cindex converter
|
||
|
||
The ODT export back-end works with popular converters with little or
|
||
no extra configuration. See @ref{Extending ODT export}. The following is
|
||
for unsupported converters or tweaking existing defaults.
|
||
|
||
@table @asis
|
||
@item Register the converter
|
||
@vindex org-export-odt-convert-processes
|
||
Add the name of the converter to the @code{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.
|
||
|
||
@item Configure its capabilities
|
||
@vindex org-export-odt-convert-capabilities
|
||
Specify which formats the converter can handle by customizing the
|
||
variable @code{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.
|
||
|
||
@item Choose the converter
|
||
@vindex org-export-odt-convert-process
|
||
Select the newly added converter as the preferred one by
|
||
customizing the option @code{org-odt-convert-process}.
|
||
@end table
|
||
|
||
@anchor{Working with OpenDocument style files}
|
||
@subsubheading Working with OpenDocument style files
|
||
|
||
@cindex styles, custom
|
||
@cindex template, custom
|
||
|
||
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 @code{org-odt-styles-dir}. The two files are:
|
||
|
||
@table @asis
|
||
@item @samp{OrgOdtStyles.xml} @anchor{x-orgodtstyles-xml}
|
||
This file contributes to the @samp{styles.xml} file of the final ODT
|
||
document. This file gets modified for the following purposes:
|
||
|
||
@enumerate
|
||
@item
|
||
To control outline numbering based on user settings;
|
||
|
||
@item
|
||
To add styles generated by @samp{htmlfontify.el} for fontification of
|
||
code blocks.
|
||
@end enumerate
|
||
|
||
@item @samp{OrgOdtContentTemplate.xml} @anchor{x-orgodtcontenttemplate-xml}
|
||
This file contributes to the @samp{content.xml} file of the final ODT
|
||
document. The contents of the Org outline are inserted between the
|
||
@samp{<office:text>} @dots{} @samp{</office:text>} elements of this file.
|
||
|
||
Apart from serving as a template file for the final @samp{content.xml},
|
||
the file serves the following purposes:
|
||
|
||
@enumerate
|
||
@item
|
||
It contains automatic styles for formatting of tables which are
|
||
referenced by the exporter;
|
||
|
||
@item
|
||
It contains @samp{<text:sequence-decl>} @dots{} @samp{</text:sequence-decl>}
|
||
elements that control numbering of tables, images, equations, and
|
||
similar entities.
|
||
@end enumerate
|
||
@end table
|
||
|
||
@anchor{x-overriding-factory-styles} 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.
|
||
|
||
@table @asis
|
||
@item @code{org-odt-styles-file}
|
||
The ODT export back-end uses the file pointed to by this
|
||
variable, such as @samp{styles.xml}, for the final output. It can
|
||
take one of the following values:
|
||
|
||
@table @asis
|
||
@item @samp{FILE.xml}
|
||
Use this file instead of the default @samp{styles.xml}
|
||
|
||
@item @samp{FILE.odt} or @samp{FILE.ott}
|
||
Use the @samp{styles.xml} contained in the specified OpenDocument
|
||
Text or Template file
|
||
|
||
@item @samp{FILE.odt} or @samp{FILE.ott} and a subset of included files
|
||
Use the @samp{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 @samp{styles.xml} file references additional
|
||
files like header and footer images.
|
||
|
||
@item @code{nil}
|
||
Use the default @samp{styles.xml}.
|
||
@end table
|
||
|
||
@item @code{org-odt-content-template-file}
|
||
Use this variable to specify the blank @samp{content.xml} used in the
|
||
final output.
|
||
@end table
|
||
|
||
@anchor{Creating one-off styles}
|
||
@subsubheading 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.
|
||
|
||
@table @asis
|
||
@item Embedding ODT tags as part of regular text
|
||
Enclose OpenDocument syntax in @samp{@@@@odt:...@@@@} for inline markup.
|
||
For example, to highlight a region of text do the following:
|
||
|
||
@example
|
||
@@@@odt:<text:span text:style-name="Highlight">This is highlighted
|
||
text</text:span>@@@@. But this is regular text.
|
||
@end example
|
||
|
||
@strong{Hint:} To see the above example in action, edit the @samp{styles.xml}
|
||
(see @ref{x-orgodtstyles-xml, , Factory styles}) and add a custom @emph{Highlight} style as shown
|
||
below:
|
||
|
||
@example
|
||
<style:style style:name="Highlight" style:family="text">
|
||
<style:text-properties fo:background-color="#ff0000"/>
|
||
</style:style>
|
||
@end example
|
||
|
||
@item Embedding a one-line OpenDocument XML
|
||
@cindex @samp{ODT}, keyword
|
||
The ODT export back-end can read one-liner options with @samp{#+ODT:}
|
||
in the Org file. For example, to force a page break:
|
||
|
||
@example
|
||
#+ODT: <text:p text:style-name="PageBreak"/>
|
||
@end example
|
||
|
||
@strong{Hint:} To see the above example in action, edit your
|
||
@samp{styles.xml} (see @ref{x-orgodtstyles-xml, , Factory styles}) and add a custom @samp{PageBreak}
|
||
style as shown below.
|
||
|
||
@example
|
||
<style:style style:name="PageBreak" style:family="paragraph"
|
||
style:parent-style-name="Text_20_body">
|
||
<style:paragraph-properties fo:break-before="page"/>
|
||
</style:style>
|
||
@end example
|
||
|
||
@item Embedding a block of OpenDocument XML
|
||
The ODT export back-end can also read ODT export blocks for
|
||
OpenDocument XML. Such blocks use the @samp{#+BEGIN_EXPORT odt}
|
||
@dots{} @samp{#+END_EXPORT} constructs.
|
||
|
||
For example, to create a one-off paragraph that uses bold text,
|
||
do the following:
|
||
|
||
@example
|
||
#+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
|
||
@end example
|
||
@end table
|
||
|
||
@anchor{Customizing tables in ODT export}
|
||
@subsubheading Customizing tables in ODT export
|
||
|
||
@cindex tables, in ODT export
|
||
@cindex @samp{ATTR_ODT}, keyword
|
||
|
||
Override the default table format by specifying a custom table style
|
||
with the @samp{#+ATTR_ODT} line. For a discussion on default formatting of
|
||
tables, see @ref{Tables in ODT export}.
|
||
|
||
This feature closely mimics the way table templates are defined in the
|
||
OpenDocument-v1.2 specification.@footnote{@uref{http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html, OpenDocument-v1.2 Specification}}
|
||
|
||
@vindex org-odt-table-styles
|
||
For quick preview of this feature, install the settings below and export the
|
||
table that follows:
|
||
|
||
@lisp
|
||
(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))))))
|
||
@end lisp
|
||
|
||
@example
|
||
#+ATTR_ODT: :style TableWithHeaderRowAndColumn
|
||
| Name | Phone | Age |
|
||
| Peter | 1234 | 17 |
|
||
| Anna | 4321 | 25 |
|
||
@end example
|
||
|
||
The example above used @samp{Custom} template and installed two table
|
||
styles @samp{TableWithHeaderRowAndColumn} and
|
||
@samp{TableWithFirstRowandLastRow}. @strong{Important:} The OpenDocument styles
|
||
needed for producing the above template were pre-defined. They are
|
||
available in the section marked @samp{Custom Table Template} in
|
||
@samp{OrgOdtContentTemplate.xml} (see @ref{x-orgodtcontenttemplate-xml, , Factory styles}). For adding new
|
||
templates, define new styles there.
|
||
|
||
To use this feature proceed as follows:
|
||
|
||
@enumerate
|
||
@item
|
||
Create a table template@footnote{See the @samp{<table:table-template>} element of the
|
||
OpenDocument-v1.2 specification.}.
|
||
|
||
A table template is set of @samp{table-cell} and @samp{paragraph} styles for
|
||
each of the following table cell categories:
|
||
|
||
@itemize
|
||
@item
|
||
Body
|
||
@item
|
||
First column
|
||
@item
|
||
Last column
|
||
@item
|
||
First row
|
||
@item
|
||
Last row
|
||
@item
|
||
Even row
|
||
@item
|
||
Odd row
|
||
@item
|
||
Even column
|
||
@item
|
||
Odd Column
|
||
@end itemize
|
||
|
||
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 @samp{Custom}, the needed style names are
|
||
listed in the following table.
|
||
|
||
@multitable {aaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
|
||
@headitem Cell type
|
||
@tab Cell style
|
||
@tab Paragraph style
|
||
@item Body
|
||
@tab @samp{CustomTableCell}
|
||
@tab @samp{CustomTableParagraph}
|
||
@item First column
|
||
@tab @samp{CustomFirstColumnTableCell}
|
||
@tab @samp{CustomFirstColumnTableParagraph}
|
||
@item Last column
|
||
@tab @samp{CustomLastColumnTableCell}
|
||
@tab @samp{CustomLastColumnTableParagraph}
|
||
@item First row
|
||
@tab @samp{CustomFirstRowTableCell}
|
||
@tab @samp{CustomFirstRowTableParagraph}
|
||
@item Last row
|
||
@tab @samp{CustomLastRowTableCell}
|
||
@tab @samp{CustomLastRowTableParagraph}
|
||
@item Even row
|
||
@tab @samp{CustomEvenRowTableCell}
|
||
@tab @samp{CustomEvenRowTableParagraph}
|
||
@item Odd row
|
||
@tab @samp{CustomOddRowTableCell}
|
||
@tab @samp{CustomOddRowTableParagraph}
|
||
@item Even column
|
||
@tab @samp{CustomEvenColumnTableCell}
|
||
@tab @samp{CustomEvenColumnTableParagraph}
|
||
@item Odd column
|
||
@tab @samp{CustomOddColumnTableCell}
|
||
@tab @samp{CustomOddColumnTableParagraph}
|
||
@end multitable
|
||
|
||
To create a table template with the name @samp{Custom}, define the above
|
||
styles in the @samp{<office:automatic-styles>} @dots{}
|
||
@samp{</office:automatic-styles>} element of the content template file
|
||
(see @ref{x-orgodtcontenttemplate-xml, , Factory styles}).
|
||
|
||
@item
|
||
Define a table style@footnote{See the attributes @samp{table:template-name},
|
||
@samp{table:use-first-row-styles}, @samp{table:use-last-row-styles},
|
||
@samp{table:use-first-column-styles}, @samp{table:use-last-column-styles},
|
||
@samp{table:use-banding-rows-styles}, and @samp{table:use-banding-column-styles}
|
||
of the @samp{<table:table>} element in the OpenDocument-v1.2 specification.}.
|
||
|
||
@vindex org-odt-table-styles
|
||
To define a table style, create an entry for the style in the
|
||
variable @code{org-odt-table-styles} and specify the following:
|
||
|
||
@itemize
|
||
@item
|
||
the name of the table template created in step (1),
|
||
@item
|
||
the set of cell styles in that template that are to be activated.
|
||
@end itemize
|
||
|
||
For example, the entry below defines two different table styles
|
||
@samp{TableWithHeaderRowAndColumn} and @samp{TableWithFirstRowandLastRow}
|
||
based on the same template @samp{Custom}. The styles achieve their
|
||
intended effect by selectively activating the individual cell
|
||
styles in that template.
|
||
|
||
@lisp
|
||
(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))))))
|
||
@end lisp
|
||
|
||
@item
|
||
Associate a table with the table style.
|
||
|
||
To do this, specify the table style created in step (2) as part of
|
||
the @samp{ATTR_ODT} line as shown below.
|
||
|
||
@example
|
||
#+ATTR_ODT: :style TableWithHeaderRowAndColumn
|
||
| Name | Phone | Age |
|
||
| Peter | 1234 | 17 |
|
||
| Anna | 4321 | 25 |
|
||
@end example
|
||
@end enumerate
|
||
|
||
@anchor{Validating OpenDocument XML}
|
||
@subsubheading Validating OpenDocument XML
|
||
|
||
Sometimes ODT format files may not open due to @samp{.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
|
||
@samp{.odt} files have to be decompressed using @samp{zip}. Note that @samp{.odt}
|
||
files are ZIP archives: @ref{File Archives,,,emacs,}. The contents of
|
||
ODT files are in XML. For general help with validation---and
|
||
schema-sensitive editing---of XML files:
|
||
@ref{Introduction,,,nxml-mode,}.
|
||
|
||
@vindex org-export-odt-schema-dir
|
||
Customize @code{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
|
||
@code{rng-schema-locating-files}.
|
||
|
||
@node Org Export
|
||
@section Org Export
|
||
|
||
@cindex Org export
|
||
@emph{org} export back-end creates a normalized version of the Org document
|
||
in current buffer. The exporter evaluates Babel code (see @ref{Evaluating Code Blocks}) and removes content specific to other back-ends.
|
||
|
||
@anchor{Org export commands}
|
||
@subheading Org export commands
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-e O o} (@code{org-org-export-to-org})
|
||
@kindex C-c C-e O o
|
||
@findex org-org-export-to-org
|
||
Export as an Org file with a @samp{.org} extension. For @samp{myfile.org},
|
||
Org exports to @samp{myfile.org.org}, overwriting without warning.
|
||
|
||
@item @kbd{C-c C-e O v} (~~)
|
||
@kindex C-c C-e O v
|
||
Export to an Org file, then open it.
|
||
@end table
|
||
|
||
@node Texinfo Export
|
||
@section 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.
|
||
* Special blocks in Texinfo export:: Special block attributes.
|
||
* A Texinfo example:: Processing Org to Texinfo.
|
||
@end menu
|
||
|
||
@node Texinfo export commands
|
||
@subsection Texinfo export commands
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-e i t} (@code{org-texinfo-export-to-texinfo})
|
||
@kindex C-c C-e i t
|
||
@findex org-texinfo-export-to-texinfo
|
||
Export as a Texinfo file with @samp{.texi} extension. For
|
||
@samp{myfile.org}, Org exports to @samp{myfile.texi}, overwriting without
|
||
warning.
|
||
|
||
@item @kbd{C-c C-e i i} (@code{org-texinfo-export-to-info})
|
||
@kindex C-c C-e i i
|
||
@findex org-texinfo-export-to-info
|
||
@vindex org-texinfo-info-process
|
||
Export to Texinfo format first and then process it to make an
|
||
Info file. To generate other formats, such as DocBook, customize
|
||
the @code{org-texinfo-info-process} variable.
|
||
@end table
|
||
|
||
@node Texinfo specific export settings
|
||
@subsection 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 @ref{Export Settings}).
|
||
|
||
@table @asis
|
||
@item @samp{SUBTITLE}
|
||
@cindex @samp{SUBTITLE}, keyword
|
||
The document subtitle.
|
||
|
||
@item @samp{SUBAUTHOR}
|
||
@cindex @samp{SUBAUTHOR}, keyword
|
||
Additional authors for the document.
|
||
|
||
@item @samp{TEXINFO_FILENAME}
|
||
@cindex @samp{TEXINFO_FILENAME}, keyword
|
||
The Texinfo filename.
|
||
|
||
@item @samp{TEXINFO_CLASS}
|
||
@cindex @samp{TEXINFO_CLASS}, keyword
|
||
@vindex org-texinfo-default-class
|
||
The default document class (@code{org-texinfo-default-class}), which
|
||
must be a member of @code{org-texinfo-classes}.
|
||
|
||
@item @samp{TEXINFO_HEADER}
|
||
@cindex @samp{TEXINFO_HEADER}, keyword
|
||
Arbitrary lines inserted at the end of the header.
|
||
|
||
@item @samp{TEXINFO_POST_HEADER}
|
||
@cindex @samp{TEXINFO_POST_HEADER}, keyword
|
||
Arbitrary lines inserted after the end of the header.
|
||
|
||
@item @samp{TEXINFO_DIR_CATEGORY}
|
||
@cindex @samp{TEXINFO_DIR_CATEGORY}, keyword
|
||
The directory category of the document.
|
||
|
||
@item @samp{TEXINFO_DIR_TITLE}
|
||
@cindex @samp{TEXINFO_DIR_TITLE}, keyword
|
||
The directory title of the document.
|
||
|
||
@item @samp{TEXINFO_DIR_DESC}
|
||
@cindex @samp{TEXINFO_DIR_DESC}, keyword
|
||
The directory description of the document.
|
||
|
||
@item @samp{TEXINFO_PRINTED_TITLE}
|
||
@cindex @samp{TEXINFO_PRINTED_TITLE}, keyword
|
||
The printed title of the document.
|
||
@end table
|
||
|
||
@node Texinfo file header
|
||
@subsection Texinfo file header
|
||
|
||
@cindex @samp{TEXINFO_FILENAME}, keyword
|
||
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 @samp{TEXINFO_FILENAME} keyword.
|
||
|
||
@vindex org-texinfo-coding-system
|
||
@cindex @samp{TEXINFO_HEADER}, keyword
|
||
Along with the output's file name, the Texinfo header also contains
|
||
language details (see @ref{Export Settings}) and encoding system as set in
|
||
the @code{org-texinfo-coding-system} variable. Insert @samp{TEXINFO_HEADER}
|
||
keywords for each additional command in the header, for example:
|
||
|
||
@example
|
||
#+TEXINFO_HEADER: @@synindex
|
||
@end example
|
||
|
||
@cindex @samp{TEXINFO_CLASS}, keyword
|
||
@vindex org-texinfo-classes
|
||
Instead of repeatedly installing the same set of commands, define
|
||
a class in @code{org-texinfo-classes} once, and then activate it in the
|
||
document by setting the @samp{TEXINFO_CLASS} keyword to that class.
|
||
|
||
@node Texinfo title and copyright page
|
||
@subsection Texinfo title and copyright page
|
||
|
||
@cindex @samp{TEXINFO_PRINTED_TITLE}, keyword
|
||
The default template for hard copy output has a title page with
|
||
@samp{TITLE} and @samp{AUTHOR} keywords (see @ref{Export Settings}). To replace the
|
||
regular title with something different for the printed version, use
|
||
the @samp{TEXINFO_PRINTED_TITLE} and @samp{SUBTITLE} keywords. Both expect raw
|
||
Texinfo code for setting their values.
|
||
|
||
@cindex @samp{SUBAUTHOR}, keyword
|
||
If one @samp{AUTHOR} line is not sufficient, add multiple @samp{SUBAUTHOR}
|
||
keywords. They have to be set in raw Texinfo code.
|
||
|
||
@example
|
||
#+AUTHOR: Jane Smith
|
||
#+SUBAUTHOR: John Doe
|
||
#+TEXINFO_PRINTED_TITLE: This Long Title@@@@inlinefmt@{tex,@@*@} Is Broken in @@TeX@{@}
|
||
@end example
|
||
|
||
@cindex @samp{COPYING}, property
|
||
Copying material is defined in a dedicated headline with a non-@code{nil}
|
||
@samp{COPYING} property. The back-end inserts the contents within
|
||
a @samp{@@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.
|
||
|
||
@example
|
||
* 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.
|
||
@end example
|
||
|
||
@node Info directory file
|
||
@subsection Info directory file
|
||
|
||
@cindex @samp{dir} file, in Texinfo export
|
||
@cindex Info directory file, in Texinfo export
|
||
@cindex @code{install-info}, in Texinfo export
|
||
|
||
@cindex @samp{TEXINFO_DIR_CATEGORY}, keyword
|
||
@cindex @samp{TEXINFO_DIR_TITLE}, keyword
|
||
@cindex @samp{TEXINFO_DIR_DESC}, keyword
|
||
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: @samp{TEXINFO_DIR_CATEGORY}, @samp{TEXINFO_DIR_TITLE},
|
||
and @samp{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:
|
||
|
||
@example
|
||
#+TEXINFO_DIR_CATEGORY: Emacs
|
||
#+TEXINFO_DIR_TITLE: Org Mode: (org)
|
||
#+TEXINFO_DIR_DESC: Outline-based notes management and organizer
|
||
@end example
|
||
|
||
@node Headings and sectioning structure
|
||
@subsection Headings and sectioning structure
|
||
|
||
@vindex org-texinfo-classes
|
||
@vindex org-texinfo-default-class
|
||
@cindex @samp{TEXINFO_CLASS}, keyword
|
||
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
|
||
@code{@@chapter} and lower-level headlines to unnumbered chapters tagged as
|
||
@code{@@unnumbered}. To override such mappings to introduce @code{@@part} or
|
||
other Texinfo structuring commands, define a new class in
|
||
@code{org-texinfo-classes}. Activate the new class with the
|
||
@samp{TEXINFO_CLASS} keyword. When no new class is defined and activated,
|
||
the Texinfo export back-end defaults to the
|
||
@code{org-texinfo-default-class}.
|
||
|
||
If an Org headline's level has no associated Texinfo structuring
|
||
command, or is below a certain threshold (see @ref{Export Settings}), then
|
||
the Texinfo export back-end makes it into a list item.
|
||
|
||
@cindex @samp{APPENDIX}, property
|
||
The Texinfo export back-end makes any headline with a non-@code{nil}
|
||
@samp{APPENDIX} property into an appendix. This happens independent of the
|
||
Org headline level or the @samp{TEXINFO_CLASS} keyword.
|
||
|
||
@cindex @samp{ALT_TITLE}, property
|
||
@cindex @samp{DESCRIPTION}, property
|
||
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 @samp{ALT_TITLE} property (see @ref{Table of Contents}). Texinfo menu entries also have an option for a longer
|
||
@samp{DESCRIPTION} property. Here's an example that uses both to override
|
||
the default menu entry:
|
||
|
||
@example
|
||
* Controlling Screen Display
|
||
:PROPERTIES:
|
||
:ALT_TITLE: Display
|
||
:DESCRIPTION: Controlling Screen Display
|
||
:END:
|
||
@end example
|
||
|
||
@cindex Top node, in Texinfo export
|
||
The text before the first headline belongs to the @emph{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 @samp{.texi}
|
||
file. See @ref{The Top Node,,,texinfo,}, for more information.
|
||
|
||
@node Indices
|
||
@subsection Indices
|
||
|
||
@cindex @samp{CINDEX}, keyword
|
||
@cindex concept index, in Texinfo export
|
||
@cindex @samp{FINDEX}, keyword
|
||
@cindex function index, in Texinfo export
|
||
@cindex @samp{KINDEX}, keyword
|
||
@cindex keystroke index, in Texinfo export
|
||
@cindex @samp{PINDEX}, keyword
|
||
@cindex program index, in Texinfo export
|
||
@cindex @samp{TINDEX}, keyword
|
||
@cindex data type index, in Texinfo export
|
||
@cindex @samp{VINDEX}, keyword
|
||
@cindex variable index, in Texinfo export
|
||
The Texinfo export back-end recognizes these indexing keywords if used
|
||
in the Org file: @samp{CINDEX}, @samp{FINDEX}, @samp{KINDEX}, @samp{PINDEX}, @samp{TINDEX} and
|
||
@samp{VINDEX}. Write their value as verbatim Texinfo code; in particular,
|
||
@samp{@{}, @samp{@}} and @samp{@@} characters need to be escaped with @samp{@@} if they do not
|
||
belong to a Texinfo command.
|
||
|
||
@example
|
||
#+CINDEX: Defining indexing entries
|
||
@end example
|
||
|
||
@cindex @samp{INDEX}, property
|
||
For the back-end to generate an index entry for a headline, set the
|
||
@samp{INDEX} property to @samp{cp} or @samp{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.
|
||
|
||
@example
|
||
* Concept Index
|
||
:PROPERTIES:
|
||
:INDEX: cp
|
||
:END:
|
||
@end example
|
||
|
||
@node Quoting Texinfo code
|
||
@subsection Quoting Texinfo code
|
||
|
||
Use any of the following three methods to insert or escape raw Texinfo
|
||
code:
|
||
|
||
@cindex @samp{TEXINFO}, keyword
|
||
@cindex @samp{BEGIN_EXPORT texinfo}
|
||
@example
|
||
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
|
||
@end example
|
||
|
||
@node Plain lists in Texinfo export
|
||
@subsection Plain lists in Texinfo export
|
||
|
||
@cindex @samp{ATTR_TEXINFO}, keyword
|
||
@cindex two-column tables, in Texinfo export
|
||
|
||
@cindex table types, in Texinfo export
|
||
The Texinfo export back-end by default converts description lists in
|
||
the Org file using the default command @samp{@@table}, which results in
|
||
a table with two columns. To change this behavior, specify
|
||
@samp{:table-type} with @samp{ftable} or @samp{vtable} attributes. For more
|
||
information, see @ref{Two-column Tables,,,texinfo,}.
|
||
|
||
@vindex org-texinfo-table-default-markup
|
||
The Texinfo export back-end by default also applies a text highlight
|
||
based on the defaults stored in @code{org-texinfo-table-default-markup}.
|
||
To override the default highlight command, specify another one with
|
||
the @samp{:indic} attribute.
|
||
|
||
@cindex multiple items in Texinfo lists
|
||
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 @samp{:sep} attribute. Each part then becomes a new
|
||
entry in the first column of the table.
|
||
|
||
The following example illustrates all the attributes above:
|
||
|
||
@example
|
||
#+ATTR_TEXINFO: :table-type vtable :sep , :indic asis
|
||
- foo, bar :: This is the common text for variables foo and bar.
|
||
@end example
|
||
|
||
@noindent
|
||
becomes
|
||
|
||
@example
|
||
@@vtable @@asis
|
||
@@item foo
|
||
@@itemx bar
|
||
This is the common text for variables foo and bar.
|
||
@@end table
|
||
@end example
|
||
|
||
@node Tables in Texinfo export
|
||
@subsection Tables in Texinfo export
|
||
|
||
@cindex @samp{ATTR_TEXINFO}, keyword
|
||
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 @samp{:columns} attribute. See example
|
||
below.
|
||
|
||
@example
|
||
#+ATTR_TEXINFO: :columns .5 .5
|
||
| a cell | another cell |
|
||
@end example
|
||
|
||
@node Images in Texinfo export
|
||
@subsection Images in Texinfo export
|
||
|
||
@cindex @samp{ATTR_TEXINFO}, keyword
|
||
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 @samp{:width} and @samp{:height} attributes. For alternate text, use @samp{:alt}
|
||
and specify the text using Texinfo code, as shown in the example:
|
||
|
||
@example
|
||
#+ATTR_TEXINFO: :width 1in :alt Alternate @@i@{text@}
|
||
[[ridt.pdf]]
|
||
@end example
|
||
|
||
@node Special blocks in Texinfo export
|
||
@subsection Special blocks in Texinfo export
|
||
|
||
@cindex @samp{ATTR_TEXINFO}, keyword
|
||
|
||
The Texinfo export back-end converts special blocks to commands with
|
||
the same name. It also adds any @samp{:options} attributes to the end of
|
||
the command, as shown in this example:
|
||
|
||
@example
|
||
#+ATTR_TEXINFO: :options org-org-export-to-org ...
|
||
#+BEGIN_defun
|
||
A somewhat obsessive function name.
|
||
#+END_defun
|
||
@end example
|
||
|
||
@noindent
|
||
becomes
|
||
|
||
@example
|
||
@@defun org-org-export-to-org ...
|
||
A somewhat obsessive function name.
|
||
@@end defun
|
||
@end example
|
||
|
||
@node A Texinfo example
|
||
@subsection A Texinfo example
|
||
|
||
Here is a more detailed example Org file. See
|
||
@ref{GNU Sample Texts,,,texinfo,} for an equivalent example using
|
||
Texinfo code.
|
||
|
||
@example
|
||
#+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:
|
||
|
||
#+TEXINFO: @@include fdl.texi
|
||
|
||
* Index
|
||
:PROPERTIES:
|
||
:INDEX: cp
|
||
:END:
|
||
@end example
|
||
|
||
@node iCalendar Export
|
||
@section iCalendar Export
|
||
|
||
@cindex 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.
|
||
|
||
@vindex org-icalendar-include-todo
|
||
@vindex org-icalendar-use-deadline
|
||
@vindex org-icalendar-use-scheduled
|
||
The iCalendar export back-end can also incorporate TODO entries based
|
||
on the configuration of the @code{org-icalendar-include-todo} variable.
|
||
The back-end exports plain timestamps as @samp{VEVENT}, TODO items as
|
||
@samp{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 @code{org-icalendar-use-deadline} and
|
||
@code{org-icalendar-use-scheduled} variables for more details.
|
||
|
||
@vindex org-icalendar-categories
|
||
@vindex org-icalendar-alarm-time
|
||
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 @code{org-icalendar-categories}. To assign
|
||
clock alarms based on time, configure the @code{org-icalendar-alarm-time}
|
||
variable.
|
||
|
||
@vindex org-icalendar-store-UID
|
||
@cindex @samp{ID}, property
|
||
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 @code{org-icalendar-store-UID}. The back-end looks for the @samp{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.
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-e c f} (@code{org-icalendar-export-to-ics})
|
||
@kindex C-c C-e c f
|
||
@findex org-icalendar-export-to-ics
|
||
Create iCalendar entries from the current Org buffer and store
|
||
them in the same directory, using a file extension @samp{.ics}.
|
||
|
||
@item @kbd{C-c C-e c a} (@code{org-icalendar-export-agenda-files})
|
||
@kindex C-c C-e c a
|
||
@findex org-icalendar-export-agenda-files
|
||
Create iCalendar entries from Org files in @code{org-agenda-files} and
|
||
store in a separate iCalendar file for each Org file.
|
||
|
||
@item @kbd{C-c C-e c c} (@code{org-icalendar-combine-agenda-files})
|
||
@kindex C-c C-e c c
|
||
@findex org-icalendar-combine-agenda-files
|
||
@vindex org-icalendar-combined-agenda-file
|
||
Create a combined iCalendar file from Org files in
|
||
@code{org-agenda-files} and write it to
|
||
@code{org-icalendar-combined-agenda-file} file name.
|
||
@end table
|
||
|
||
@cindex @samp{SUMMARY}, property
|
||
@cindex @samp{DESCRIPTION}, property
|
||
@cindex @samp{LOCATION}, property
|
||
@cindex @samp{TIMEZONE}, property
|
||
The iCalendar export back-end includes @samp{SUMMARY}, @samp{DESCRIPTION},
|
||
@samp{LOCATION} and @samp{TIMEZONE} properties from the Org entries when
|
||
exporting. To force the back-end to inherit the @samp{LOCATION} and
|
||
@samp{TIMEZONE} properties, configure the @code{org-use-property-inheritance}
|
||
variable.
|
||
|
||
@vindex org-icalendar-include-body
|
||
When Org entries do not have @samp{SUMMARY}, @samp{DESCRIPTION} and @samp{LOCATION}
|
||
properties, the iCalendar export back-end derives the summary from the
|
||
headline, and derives the description from the body of the Org item.
|
||
The @code{org-icalendar-include-body} variable limits the maximum number of
|
||
characters of the content are turned into its description.
|
||
|
||
The @samp{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.,
|
||
@samp{Asia/Almaty}. Alternately, the property value can be @samp{UTC}, to force
|
||
UTC time for this entry only.
|
||
|
||
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.
|
||
|
||
@node Other Built-in Back-ends
|
||
@section Other Built-in Back-ends
|
||
|
||
Other export back-ends included with Org are:
|
||
|
||
@itemize
|
||
@item
|
||
@samp{ox-man.el}: Export to a man page.
|
||
@end itemize
|
||
|
||
To activate such back-ends, either customize @code{org-export-backends} or
|
||
load directly with @code{(require 'ox-man)}. On successful load, the
|
||
back-end adds new keys in the export dispatcher (see @ref{The Export Dispatcher}).
|
||
|
||
Follow the comment section of such files, for example, @samp{ox-man.el},
|
||
for usage and configuration details.
|
||
|
||
@node Advanced Configuration
|
||
@section Advanced Configuration
|
||
|
||
|
||
|
||
@anchor{Hooks}
|
||
@subheading Hooks
|
||
|
||
@vindex org-export-before-processing-hook
|
||
@vindex org-export-before-parsing-hook
|
||
The export process executes two hooks before the actual exporting
|
||
begins. The first hook, @code{org-export-before-processing-hook}, runs
|
||
before any expansions of macros, Babel code, and include keywords in
|
||
the buffer. The second hook, @code{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:
|
||
|
||
@lisp
|
||
(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)
|
||
@end lisp
|
||
|
||
@anchor{Filters}
|
||
@subheading Filters
|
||
|
||
@cindex Filters, exporting
|
||
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: @code{org-export-filter-TYPE-functions}, where @var{TYPE}
|
||
is the type targeted by the filter. Valid types are:
|
||
|
||
@multitable @columnfractions 0.33 0.33 0.33
|
||
@item body
|
||
@tab bold
|
||
@tab babel-call
|
||
@item center-block
|
||
@tab clock
|
||
@tab code
|
||
@item diary-sexp
|
||
@tab drawer
|
||
@tab dynamic-block
|
||
@item entity
|
||
@tab example-block
|
||
@tab export-block
|
||
@item export-snippet
|
||
@tab final-output
|
||
@tab fixed-width
|
||
@item footnote-definition
|
||
@tab footnote-reference
|
||
@tab headline
|
||
@item horizontal-rule
|
||
@tab inline-babel-call
|
||
@tab inline-src-block
|
||
@item inlinetask
|
||
@tab italic
|
||
@tab item
|
||
@item keyword
|
||
@tab latex-environment
|
||
@tab latex-fragment
|
||
@item line-break
|
||
@tab link
|
||
@tab node-property
|
||
@item options
|
||
@tab paragraph
|
||
@tab parse-tree
|
||
@item plain-list
|
||
@tab plain-text
|
||
@tab planning
|
||
@item property-drawer
|
||
@tab quote-block
|
||
@tab radio-target
|
||
@item section
|
||
@tab special-block
|
||
@tab src-block
|
||
@item statistics-cookie
|
||
@tab strike-through
|
||
@tab subscript
|
||
@item superscript
|
||
@tab table
|
||
@tab table-cell
|
||
@item table-row
|
||
@tab target
|
||
@tab timestamp
|
||
@item underline
|
||
@tab verbatim
|
||
@tab verse-block
|
||
@end multitable
|
||
|
||
Here is an example filter that replaces non-breaking spaces @code{ } in the
|
||
Org buffer with @samp{~} for the @LaTeX{} back-end.
|
||
|
||
@lisp
|
||
(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)
|
||
@end lisp
|
||
|
||
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
|
||
@code{org-export-derived-backend-p} predicate that tests for @emph{latex}
|
||
back-end or any other back-end, such as @emph{beamer}, derived from
|
||
@emph{latex}.
|
||
|
||
@anchor{Defining filters for individual files}
|
||
@subheading Defining filters for individual files
|
||
|
||
The Org export can filter not just for back-ends, but also for
|
||
specific files through the @samp{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.
|
||
|
||
@example
|
||
#+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
|
||
@end example
|
||
|
||
@anchor{Extending an existing back-end}
|
||
@subheading 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 @emph{ascii} back-end display the language used
|
||
in a source code block. Also make it display only when some attribute
|
||
is non-@code{nil}, like the following:
|
||
|
||
@example
|
||
#+ATTR_ASCII: :language t
|
||
@end example
|
||
|
||
Then extend ASCII back-end with a custom ``my-ascii'' back-end.
|
||
|
||
@lisp
|
||
(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)))
|
||
@end lisp
|
||
|
||
The @code{my-ascii-src-block} function looks at the attribute above the
|
||
current element. If not true, hands over to @emph{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 @code{src-block} type elements.
|
||
|
||
To use the newly defined back-end, evaluate the following from an Org
|
||
buffer:
|
||
|
||
@lisp
|
||
(org-export-to-buffer 'my-ascii "*Org MY-ASCII Export*")
|
||
@end lisp
|
||
|
||
Further steps to consider would be an interactive function,
|
||
self-installing an item in the export dispatcher menu, and other
|
||
user-friendly improvements.
|
||
|
||
@node Export in Foreign Buffers
|
||
@section 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:
|
||
|
||
@table @asis
|
||
@item @code{org-html-convert-region-to-html}
|
||
@findex org-html-convert-region-to-html
|
||
Convert the selected region into HTML.
|
||
|
||
@item @code{org-latex-convert-region-to-latex}
|
||
@findex org-latex-convert-region-to-latex
|
||
Convert the selected region into @LaTeX{}.
|
||
|
||
@item @code{org-texinfo-convert-region-to-texinfo}
|
||
@findex org-texinfo-convert-region-to-texinfo
|
||
Convert the selected region into Texinfo.
|
||
|
||
@item @code{org-md-convert-region-to-md}
|
||
@findex org-md-convert-region-to-md
|
||
Convert the selected region into Markdown.
|
||
@end table
|
||
|
||
In-place conversions are particularly handy for quick conversion of
|
||
tables and lists in foreign buffers. For example, turn on the minor
|
||
mode @kbd{M-x orgstruct-mode} in an HTML buffer, then use the
|
||
convenient Org keyboard commands to create a list, select it, and
|
||
covert it to HTML with @kbd{M-x org-html-convert-region-to-html}.
|
||
|
||
@node Publishing
|
||
@chapter Publishing
|
||
|
||
@cindex publishing
|
||
|
||
Org includes a publishing management system that allows you to
|
||
configure automatic HTML conversion of @emph{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.
|
||
@end menu
|
||
|
||
@node Configuration
|
||
@section 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.
|
||
@end menu
|
||
|
||
@node Project alist
|
||
@subsection The variable @code{org-publish-project-alist}
|
||
|
||
@cindex projects, for publishing
|
||
|
||
@vindex org-publish-project-alist
|
||
Publishing is configured almost entirely through setting the value of
|
||
one variable, called @code{org-publish-project-alist}. Each element of the
|
||
list configures one project, and may be in one of the two following
|
||
forms:
|
||
|
||
@lisp
|
||
("project-name" :property value :property value ...)
|
||
@end lisp
|
||
|
||
@noindent
|
||
i.e., a well-formed property list with alternating keys and values,
|
||
or:
|
||
|
||
@lisp
|
||
("project-name" :components ("project-name" "project-name" ...))
|
||
@end lisp
|
||
|
||
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 @code{: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.
|
||
|
||
@node Sources and destinations
|
||
@subsection Sources and destinations for files
|
||
|
||
@cindex directories, for publishing
|
||
|
||
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.
|
||
|
||
@table @asis
|
||
@item @code{:base-directory}
|
||
Directory containing publishing source files.
|
||
|
||
@item @code{: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 @ref{Uploading Files}).
|
||
|
||
@item @code{:preparation-function}
|
||
Function or list of functions to be called before starting the
|
||
publishing process, for example, to run @samp{make} for updating files
|
||
to be published. Each preparation function is called with
|
||
a single argument, the project property list.
|
||
|
||
@item @code{: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.
|
||
@end table
|
||
|
||
@node Selecting files
|
||
@subsection Selecting files
|
||
|
||
@cindex files, selecting for publishing
|
||
|
||
By default, all files with extension @samp{.org} in the base directory are
|
||
considered part of the project. This can be modified by setting the
|
||
following properties
|
||
|
||
@table @asis
|
||
@item @code{:base-extension}
|
||
Extension---without the dot---of source files. This actually
|
||
is a regular expression. Set this to the symbol @code{any} if you
|
||
want to get all files in @code{:base-directory}, even without
|
||
extension.
|
||
|
||
@item @code{:exclude}
|
||
Regular expression to match file names that should not be published,
|
||
even though they have been selected on the basis of their extension.
|
||
|
||
@item @code{:include}
|
||
List of files to be included regardless of @code{:base-extension} and
|
||
@code{:exclude}.
|
||
|
||
@item @code{:recursive}
|
||
Non-@code{nil} means, check base-directory recursively for files to
|
||
publish.
|
||
@end table
|
||
|
||
@node Publishing action
|
||
@subsection Publishing action
|
||
|
||
@cindex action, for publishing
|
||
|
||
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
|
||
@code{org-publish-org-to-html} which calls the HTML exporter (see @ref{HTML Export}). But you can also publish your content as PDF files using
|
||
@code{org-publish-org-to-pdf}, or as ASCII, Texinfo, etc., using the
|
||
corresponding functions.
|
||
|
||
If you want to publish the Org file as an @samp{.org} file but with
|
||
@emph{archived}, @emph{commented}, and @emph{tag-excluded} trees removed, use
|
||
@code{org-publish-org-to-org}. This produces @samp{file.org} and put it in the
|
||
publishing directory. If you want a htmlized version of this file,
|
||
set the parameter @code{:htmlized-source} to @code{t}. It produces
|
||
@samp{file.org.html} in the publishing directory@footnote{If the publishing directory is the same as the source
|
||
directory, @samp{file.org} is exported as @samp{file.org.org}, so you probably
|
||
do not want to do this.}.
|
||
|
||
Other files like images only need to be copied to the publishing
|
||
destination; for this you can use @code{org-publish-attachment}. For
|
||
non-Org files, you always need to specify the publishing function:
|
||
|
||
@table @asis
|
||
@item @code{:publishing-function}
|
||
Function executing the publication of a file. This may also be
|
||
a list of functions, which are all called in turn.
|
||
|
||
@item @code{:plain-source}
|
||
Non-@code{nil} means, publish plain source.
|
||
|
||
@item @code{:htmlized-source}
|
||
Non-@code{nil} means, publish htmlized source.
|
||
@end table
|
||
|
||
The function must accept three arguments: a property list containing
|
||
at least a @code{: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.
|
||
|
||
@node Publishing options
|
||
@subsection Options for the exporters
|
||
|
||
@cindex options, for publishing
|
||
@cindex publishing options
|
||
|
||
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.
|
||
|
||
@vindex org-publish-project-alist
|
||
When a property is given a value in @code{org-publish-project-alist}, its
|
||
setting overrides the value of the corresponding user variable, if
|
||
any, during publishing. Options set within a file (see @ref{Export Settings}), however, override everything.
|
||
|
||
@anchor{Generic properties}
|
||
@subsubheading Generic properties
|
||
|
||
@multitable {aaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
|
||
@item @code{:archived-trees}
|
||
@tab @code{org-export-with-archived-trees}
|
||
@item @code{:exclude-tags}
|
||
@tab @code{org-export-exclude-tags}
|
||
@item @code{:headline-levels}
|
||
@tab @code{org-export-headline-levels}
|
||
@item @code{:language}
|
||
@tab @code{org-export-default-language}
|
||
@item @code{:preserve-breaks}
|
||
@tab @code{org-export-preserve-breaks}
|
||
@item @code{:section-numbers}
|
||
@tab @code{org-export-with-section-numbers}
|
||
@item @code{:select-tags}
|
||
@tab @code{org-export-select-tags}
|
||
@item @code{:with-author}
|
||
@tab @code{org-export-with-author}
|
||
@item @code{:with-broken-links}
|
||
@tab @code{org-export-with-broken-links}
|
||
@item @code{:with-clocks}
|
||
@tab @code{org-export-with-clocks}
|
||
@item @code{:with-creator}
|
||
@tab @code{org-export-with-creator}
|
||
@item @code{:with-date}
|
||
@tab @code{org-export-with-date}
|
||
@item @code{:with-drawers}
|
||
@tab @code{org-export-with-drawers}
|
||
@item @code{:with-email}
|
||
@tab @code{org-export-with-email}
|
||
@item @code{:with-emphasize}
|
||
@tab @code{org-export-with-emphasize}
|
||
@item @code{:with-fixed-width}
|
||
@tab @code{org-export-with-fixed-width}
|
||
@item @code{:with-footnotes}
|
||
@tab @code{org-export-with-footnotes}
|
||
@item @code{:with-latex}
|
||
@tab @code{org-export-with-latex}
|
||
@item @code{:with-planning}
|
||
@tab @code{org-export-with-planning}
|
||
@item @code{:with-priority}
|
||
@tab @code{org-export-with-priority}
|
||
@item @code{:with-properties}
|
||
@tab @code{org-export-with-properties}
|
||
@item @code{:with-special-strings}
|
||
@tab @code{org-export-with-special-strings}
|
||
@item @code{:with-sub-superscript}
|
||
@tab @code{org-export-with-sub-superscripts}
|
||
@item @code{:with-tables}
|
||
@tab @code{org-export-with-tables}
|
||
@item @code{:with-tags}
|
||
@tab @code{org-export-with-tags}
|
||
@item @code{:with-tasks}
|
||
@tab @code{org-export-with-tasks}
|
||
@item @code{:with-timestamps}
|
||
@tab @code{org-export-with-timestamps}
|
||
@item @code{:with-title}
|
||
@tab @code{org-export-with-title}
|
||
@item @code{:with-toc}
|
||
@tab @code{org-export-with-toc}
|
||
@item @code{:with-todo-keywords}
|
||
@tab @code{org-export-with-todo-keywords}
|
||
@end multitable
|
||
|
||
@anchor{ASCII specific properties}
|
||
@subsubheading ASCII specific properties
|
||
|
||
@multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
|
||
@item @code{:ascii-bullets}
|
||
@tab @code{org-ascii-bullets}
|
||
@item @code{:ascii-caption-above}
|
||
@tab @code{org-ascii-caption-above}
|
||
@item @code{:ascii-charset}
|
||
@tab @code{org-ascii-charset}
|
||
@item @code{:ascii-global-margin}
|
||
@tab @code{org-ascii-global-margin}
|
||
@item @code{:ascii-format-drawer-function}
|
||
@tab @code{org-ascii-format-drawer-function}
|
||
@item @code{:ascii-format-inlinetask-function}
|
||
@tab @code{org-ascii-format-inlinetask-function}
|
||
@item @code{:ascii-headline-spacing}
|
||
@tab @code{org-ascii-headline-spacing}
|
||
@item @code{:ascii-indented-line-width}
|
||
@tab @code{org-ascii-indented-line-width}
|
||
@item @code{:ascii-inlinetask-width}
|
||
@tab @code{org-ascii-inlinetask-width}
|
||
@item @code{:ascii-inner-margin}
|
||
@tab @code{org-ascii-inner-margin}
|
||
@item @code{:ascii-links-to-notes}
|
||
@tab @code{org-ascii-links-to-notes}
|
||
@item @code{:ascii-list-margin}
|
||
@tab @code{org-ascii-list-margin}
|
||
@item @code{:ascii-paragraph-spacing}
|
||
@tab @code{org-ascii-paragraph-spacing}
|
||
@item @code{:ascii-quote-margin}
|
||
@tab @code{org-ascii-quote-margin}
|
||
@item @code{:ascii-table-keep-all-vertical-lines}
|
||
@tab @code{org-ascii-table-keep-all-vertical-lines}
|
||
@item @code{:ascii-table-use-ascii-art}
|
||
@tab @code{org-ascii-table-use-ascii-art}
|
||
@item @code{:ascii-table-widen-columns}
|
||
@tab @code{org-ascii-table-widen-columns}
|
||
@item @code{:ascii-text-width}
|
||
@tab @code{org-ascii-text-width}
|
||
@item @code{:ascii-underline}
|
||
@tab @code{org-ascii-underline}
|
||
@item @code{:ascii-verbatim-format}
|
||
@tab @code{org-ascii-verbatim-format}
|
||
@end multitable
|
||
|
||
@anchor{Beamer specific properties}
|
||
@subsubheading Beamer specific properties
|
||
|
||
@multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
|
||
@item @code{:beamer-theme}
|
||
@tab @code{org-beamer-theme}
|
||
@item @code{:beamer-column-view-format}
|
||
@tab @code{org-beamer-column-view-format}
|
||
@item @code{:beamer-environments-extra}
|
||
@tab @code{org-beamer-environments-extra}
|
||
@item @code{:beamer-frame-default-options}
|
||
@tab @code{org-beamer-frame-default-options}
|
||
@item @code{:beamer-outline-frame-options}
|
||
@tab @code{org-beamer-outline-frame-options}
|
||
@item @code{:beamer-outline-frame-title}
|
||
@tab @code{org-beamer-outline-frame-title}
|
||
@item @code{:beamer-subtitle-format}
|
||
@tab @code{org-beamer-subtitle-format}
|
||
@end multitable
|
||
|
||
@anchor{HTML specific properties}
|
||
@subsubheading HTML specific properties
|
||
|
||
@multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
|
||
@item @code{:html-allow-name-attribute-in-anchors}
|
||
@tab @code{org-html-allow-name-attribute-in-anchors}
|
||
@item @code{:html-checkbox-type}
|
||
@tab @code{org-html-checkbox-type}
|
||
@item @code{:html-container}
|
||
@tab @code{org-html-container-element}
|
||
@item @code{:html-divs}
|
||
@tab @code{org-html-divs}
|
||
@item @code{:html-doctype}
|
||
@tab @code{org-html-doctype}
|
||
@item @code{:html-extension}
|
||
@tab @code{org-html-extension}
|
||
@item @code{:html-footnote-format}
|
||
@tab @code{org-html-footnote-format}
|
||
@item @code{:html-footnote-separator}
|
||
@tab @code{org-html-footnote-separator}
|
||
@item @code{:html-footnotes-section}
|
||
@tab @code{org-html-footnotes-section}
|
||
@item @code{:html-format-drawer-function}
|
||
@tab @code{org-html-format-drawer-function}
|
||
@item @code{:html-format-headline-function}
|
||
@tab @code{org-html-format-headline-function}
|
||
@item @code{:html-format-inlinetask-function}
|
||
@tab @code{org-html-format-inlinetask-function}
|
||
@item @code{:html-head-extra}
|
||
@tab @code{org-html-head-extra}
|
||
@item @code{:html-head-include-default-style}
|
||
@tab @code{org-html-head-include-default-style}
|
||
@item @code{:html-head-include-scripts}
|
||
@tab @code{org-html-head-include-scripts}
|
||
@item @code{:html-head}
|
||
@tab @code{org-html-head}
|
||
@item @code{:html-home/up-format}
|
||
@tab @code{org-html-home/up-format}
|
||
@item @code{:html-html5-fancy}
|
||
@tab @code{org-html-html5-fancy}
|
||
@item @code{:html-indent}
|
||
@tab @code{org-html-indent}
|
||
@item @code{:html-infojs-options}
|
||
@tab @code{org-html-infojs-options}
|
||
@item @code{:html-infojs-template}
|
||
@tab @code{org-html-infojs-template}
|
||
@item @code{:html-inline-image-rules}
|
||
@tab @code{org-html-inline-image-rules}
|
||
@item @code{:html-inline-images}
|
||
@tab @code{org-html-inline-images}
|
||
@item @code{:html-link-home}
|
||
@tab @code{org-html-link-home}
|
||
@item @code{:html-link-org-files-as-html}
|
||
@tab @code{org-html-link-org-files-as-html}
|
||
@item @code{:html-link-up}
|
||
@tab @code{org-html-link-up}
|
||
@item @code{:html-link-use-abs-url}
|
||
@tab @code{org-html-link-use-abs-url}
|
||
@item @code{:html-mathjax-options}
|
||
@tab @code{org-html-mathjax-options}
|
||
@item @code{:html-mathjax-template}
|
||
@tab @code{org-html-mathjax-template}
|
||
@item @code{:html-metadata-timestamp-format}
|
||
@tab @code{org-html-metadata-timestamp-format}
|
||
@item @code{:html-postamble-format}
|
||
@tab @code{org-html-postamble-format}
|
||
@item @code{:html-postamble}
|
||
@tab @code{org-html-postamble}
|
||
@item @code{:html-preamble-format}
|
||
@tab @code{org-html-preamble-format}
|
||
@item @code{:html-preamble}
|
||
@tab @code{org-html-preamble}
|
||
@item @code{:html-table-align-individual-field}
|
||
@tab @code{de@{org-html-table-align-individual-fields}
|
||
@item @code{:html-table-attributes}
|
||
@tab @code{org-html-table-default-attributes}
|
||
@item @code{:html-table-caption-above}
|
||
@tab @code{org-html-table-caption-above}
|
||
@item @code{:html-table-data-tags}
|
||
@tab @code{org-html-table-data-tags}
|
||
@item @code{:html-table-header-tags}
|
||
@tab @code{org-html-table-header-tags}
|
||
@item @code{:html-table-row-tags}
|
||
@tab @code{org-html-table-row-tags}
|
||
@item @code{:html-table-use-header-tags-for-first-column}
|
||
@tab @code{org-html-table-use-header-tags-for-first-column}
|
||
@item @code{:html-tag-class-prefix}
|
||
@tab @code{org-html-tag-class-prefix}
|
||
@item @code{:html-text-markup-alist}
|
||
@tab @code{org-html-text-markup-alist}
|
||
@item @code{:html-todo-kwd-class-prefix}
|
||
@tab @code{org-html-todo-kwd-class-prefix}
|
||
@item @code{:html-toplevel-hlevel}
|
||
@tab @code{org-html-toplevel-hlevel}
|
||
@item @code{:html-use-infojs}
|
||
@tab @code{org-html-use-infojs}
|
||
@item @code{:html-validation-link}
|
||
@tab @code{org-html-validation-link}
|
||
@item @code{:html-viewport}
|
||
@tab @code{org-html-viewport}
|
||
@item @code{:html-xml-declaration}
|
||
@tab @code{org-html-xml-declaration}
|
||
@end multitable
|
||
|
||
@anchor{@LaTeX{} specific properties}
|
||
@subsubheading @LaTeX{} specific properties
|
||
|
||
@multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
|
||
@item @code{:latex-active-timestamp-format}
|
||
@tab @code{org-latex-active-timestamp-format}
|
||
@item @code{:latex-caption-above}
|
||
@tab @code{org-latex-caption-above}
|
||
@item @code{:latex-classes}
|
||
@tab @code{org-latex-classes}
|
||
@item @code{:latex-class}
|
||
@tab @code{org-latex-default-class}
|
||
@item @code{:latex-compiler}
|
||
@tab @code{org-latex-compiler}
|
||
@item @code{:latex-default-figure-position}
|
||
@tab @code{org-latex-default-figure-position}
|
||
@item @code{:latex-default-table-environment}
|
||
@tab @code{org-latex-default-table-environment}
|
||
@item @code{:latex-default-table-mode}
|
||
@tab @code{org-latex-default-table-mode}
|
||
@item @code{:latex-diary-timestamp-format}
|
||
@tab @code{org-latex-diary-timestamp-format}
|
||
@item @code{:latex-footnote-defined-format}
|
||
@tab @code{org-latex-footnote-defined-format}
|
||
@item @code{:latex-footnote-separator}
|
||
@tab @code{org-latex-footnote-separator}
|
||
@item @code{:latex-format-drawer-function}
|
||
@tab @code{org-latex-format-drawer-function}
|
||
@item @code{:latex-format-headline-function}
|
||
@tab @code{org-latex-format-headline-function}
|
||
@item @code{:latex-format-inlinetask-function}
|
||
@tab @code{org-latex-format-inlinetask-function}
|
||
@item @code{:latex-hyperref-template}
|
||
@tab @code{org-latex-hyperref-template}
|
||
@item @code{:latex-image-default-height}
|
||
@tab @code{org-latex-image-default-height}
|
||
@item @code{:latex-image-default-option}
|
||
@tab @code{org-latex-image-default-option}
|
||
@item @code{:latex-image-default-width}
|
||
@tab @code{org-latex-image-default-width}
|
||
@item @code{:latex-images-centered}
|
||
@tab @code{org-latex-images-centered}
|
||
@item @code{:latex-inactive-timestamp-format}
|
||
@tab @code{org-latex-inactive-timestamp-format}
|
||
@item @code{:latex-inline-image-rules}
|
||
@tab @code{org-latex-inline-image-rules}
|
||
@item @code{:latex-link-with-unknown-path-format}
|
||
@tab @code{org-latex-link-with-unknown-path-format}
|
||
@item @code{:latex-listings-langs}
|
||
@tab @code{org-latex-listings-langs}
|
||
@item @code{:latex-listings-options}
|
||
@tab @code{org-latex-listings-options}
|
||
@item @code{:latex-listings}
|
||
@tab @code{org-latex-listings}
|
||
@item @code{:latex-minted-langs}
|
||
@tab @code{org-latex-minted-langs}
|
||
@item @code{:latex-minted-options}
|
||
@tab @code{org-latex-minted-options}
|
||
@item @code{:latex-prefer-user-labels}
|
||
@tab @code{org-latex-prefer-user-labels}
|
||
@item @code{:latex-subtitle-format}
|
||
@tab @code{org-latex-subtitle-format}
|
||
@item @code{:latex-subtitle-separate}
|
||
@tab @code{org-latex-subtitle-separate}
|
||
@item @code{:latex-table-scientific-notation}
|
||
@tab @code{org-latex-table-scientific-notation}
|
||
@item @code{:latex-tables-booktabs}
|
||
@tab @code{org-latex-tables-booktabs}
|
||
@item @code{:latex-tables-centered}
|
||
@tab @code{org-latex-tables-centered}
|
||
@item @code{:latex-text-markup-alist}
|
||
@tab @code{org-latex-text-markup-alist}
|
||
@item @code{:latex-title-command}
|
||
@tab @code{org-latex-title-command}
|
||
@item @code{:latex-toc-command}
|
||
@tab @code{org-latex-toc-command}
|
||
@end multitable
|
||
|
||
@anchor{Markdown specific properties}
|
||
@subsubheading Markdown specific properties
|
||
|
||
@multitable {aaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaa}
|
||
@item @code{:md-footnote-format}
|
||
@tab @code{org-md-footnote-format}
|
||
@item @code{:md-footnotes-section}
|
||
@tab @code{org-md-footnotes-section}
|
||
@item @code{:md-headline-style}
|
||
@tab @code{org-md-headline-style}
|
||
@end multitable
|
||
|
||
@anchor{ODT specific properties}
|
||
@subsubheading ODT specific properties
|
||
|
||
@multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
|
||
@item @code{:odt-content-template-file}
|
||
@tab @code{org-odt-content-template-file}
|
||
@item @code{:odt-display-outline-level}
|
||
@tab @code{org-odt-display-outline-level}
|
||
@item @code{:odt-fontify-srcblocks}
|
||
@tab @code{org-odt-fontify-srcblocks}
|
||
@item @code{:odt-format-drawer-function}
|
||
@tab @code{org-odt-format-drawer-function}
|
||
@item @code{:odt-format-headline-function}
|
||
@tab @code{org-odt-format-headline-function}
|
||
@item @code{:odt-format-inlinetask-function}
|
||
@tab @code{org-odt-format-inlinetask-function}
|
||
@item @code{:odt-inline-formula-rules}
|
||
@tab @code{org-odt-inline-formula-rules}
|
||
@item @code{:odt-inline-image-rules}
|
||
@tab @code{org-odt-inline-image-rules}
|
||
@item @code{:odt-pixels-per-inch}
|
||
@tab @code{org-odt-pixels-per-inch}
|
||
@item @code{:odt-styles-file}
|
||
@tab @code{org-odt-styles-file}
|
||
@item @code{:odt-table-styles}
|
||
@tab @code{org-odt-table-styles}
|
||
@item @code{:odt-use-date-fields}
|
||
@tab @code{org-odt-use-date-fields}
|
||
@end multitable
|
||
|
||
@anchor{Texinfo specific properties}
|
||
@subsubheading Texinfo specific properties
|
||
|
||
@multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
|
||
@item @code{:texinfo-active-timestamp-format}
|
||
@tab @code{org-texinfo-active-timestamp-format}
|
||
@item @code{:texinfo-classes}
|
||
@tab @code{org-texinfo-classes}
|
||
@item @code{:texinfo-class}
|
||
@tab @code{org-texinfo-default-class}
|
||
@item @code{:texinfo-table-default-markup}
|
||
@tab @code{org-texinfo-table-default-markup}
|
||
@item @code{:texinfo-diary-timestamp-format}
|
||
@tab @code{org-texinfo-diary-timestamp-format}
|
||
@item @code{:texinfo-filename}
|
||
@tab @code{org-texinfo-filename}
|
||
@item @code{:texinfo-format-drawer-function}
|
||
@tab @code{org-texinfo-format-drawer-function}
|
||
@item @code{:texinfo-format-headline-function}
|
||
@tab @code{org-texinfo-format-headline-function}
|
||
@item @code{:texinfo-format-inlinetask-function}
|
||
@tab @code{org-texinfo-format-inlinetask-function}
|
||
@item @code{:texinfo-inactive-timestamp-format}
|
||
@tab @code{org-texinfo-inactive-timestamp-format}
|
||
@item @code{:texinfo-link-with-unknown-path-format}
|
||
@tab @code{org-texinfo-link-with-unknown-path-format}
|
||
@item @code{:texinfo-node-description-column}
|
||
@tab @code{org-texinfo-node-description-column}
|
||
@item @code{:texinfo-table-scientific-notation}
|
||
@tab @code{org-texinfo-table-scientific-notation}
|
||
@item @code{:texinfo-tables-verbatim}
|
||
@tab @code{org-texinfo-tables-verbatim}
|
||
@item @code{:texinfo-text-markup-alist}
|
||
@tab @code{org-texinfo-text-markup-alist}
|
||
@end multitable
|
||
|
||
@node Publishing links
|
||
@subsection Publishing links
|
||
|
||
@cindex links, publishing
|
||
|
||
To create a link from one Org file to another, you would use something
|
||
like @samp{[[file:foo.org][The foo]]} or simply @samp{[[file:foo.org]]} (see @ref{External Links}). When
|
||
published, this link becomes a link to @samp{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 @samp{http} link instead of
|
||
a @samp{file:} link, because @samp{file} links are converted to link to the
|
||
corresponding @samp{.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 @ref{Complex example}, for an example of this
|
||
usage.
|
||
|
||
Eventually, links between published documents can contain some search
|
||
options (see @ref{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 @samp{foo.html}.
|
||
|
||
@example
|
||
[[file:foo.org::*heading]]
|
||
[[file:foo.org::#custom-id]]
|
||
[[file:foo.org::target]]
|
||
@end example
|
||
|
||
@node Site map
|
||
@subsection Generating a sitemap
|
||
|
||
@cindex sitemap, of published pages
|
||
|
||
The following properties may be used to control publishing of
|
||
a map of files for a given project.
|
||
|
||
@table @asis
|
||
@item @code{:auto-sitemap}
|
||
When non-@code{nil}, publish a sitemap during
|
||
@code{org-publish-current-project} or @code{org-publish-all}.
|
||
|
||
@item @code{:sitemap-filename}
|
||
Filename for output of sitemap. Defaults to @samp{sitemap.org}, which
|
||
becomes @samp{sitemap.html}.
|
||
|
||
@item @code{:sitemap-title}
|
||
Title of sitemap page. Defaults to name of file.
|
||
|
||
@item @code{:sitemap-format-entry}
|
||
@findex org-publish-find-date
|
||
@findex org-publish-find-property
|
||
@findex org-publish-find-title
|
||
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 @code{org-publish-find-date},
|
||
@code{org-publish-find-title} and @code{org-publish-find-property}, to
|
||
retrieve additional information about published documents.
|
||
|
||
@item @code{: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
|
||
@code{org-list-to-generic}, @code{org-list-to-subtree} and alike. Default
|
||
value generates a plain list of links to all files in the
|
||
project.
|
||
|
||
@item @code{:sitemap-sort-folders}
|
||
Where folders should appear in the sitemap. Set this to @code{first}
|
||
(default) or @code{last} to display folders first or last,
|
||
respectively. When set to @code{ignore}, folders are ignored
|
||
altogether. Any other value mixes files and folders. This
|
||
variable has no effect when site-map style is @code{tree}.
|
||
|
||
@item @code{:sitemap-sort-files}
|
||
How the files are sorted in the site map. Set this to
|
||
@code{alphabetically} (default), @code{chronologically} or
|
||
@code{anti-chronologically}. @code{chronologically} sorts the files with
|
||
older date first while @code{anti-chronologically} sorts the files
|
||
with newer date first. @code{alphabetically} sorts the files
|
||
alphabetically. The date of a file is retrieved with
|
||
@code{org-publish-find-date}.
|
||
|
||
@item @code{:sitemap-ignore-case}
|
||
Should sorting be case-sensitive? Default @code{nil}.
|
||
|
||
@item @code{: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: @code{%t} stands for the title of the file, @code{%a} stands for
|
||
the author of the file and @code{%d} stands for the date of the file.
|
||
The date is retrieved with the @code{org-publish-find-date} function
|
||
and formatted with @code{org-publish-sitemap-date-format}. Default
|
||
@code{%t}.
|
||
|
||
@item @code{:sitemap-date-format}
|
||
Format string for the @code{format-time-string} function that tells
|
||
how a sitemap entry's date is to be formatted. This property
|
||
bypasses @code{org-publish-sitemap-date-format} which defaults to
|
||
@code{%Y-%m-%d}.
|
||
@end table
|
||
|
||
@node Generating an index
|
||
@subsection Generating an index
|
||
|
||
@cindex index, in a publishing project
|
||
|
||
Org mode can generate an index across the files of a publishing project.
|
||
|
||
@table @asis
|
||
@item @code{:makeindex}
|
||
When non-@code{nil}, generate in index in the file @samp{theindex.org} and
|
||
publish it as @samp{theindex.html}.
|
||
@end table
|
||
|
||
The file is created when first publishing a project with the
|
||
@code{:makeindex} set. The file only contains a statement @samp{#+INCLUDE:
|
||
"theindex.inc"}. You can then build around this include statement by
|
||
adding a title, style information, etc.
|
||
|
||
@cindex @samp{INDEX}, keyword
|
||
Index entries are specified with @samp{INDEX} keyword. An entry that
|
||
contains an exclamation mark creates a sub item.
|
||
|
||
@example
|
||
*** Curriculum Vitae
|
||
#+INDEX: CV
|
||
#+INDEX: Application!CV
|
||
@end example
|
||
|
||
@node Uploading Files
|
||
@section Uploading Files
|
||
|
||
@cindex rsync
|
||
@cindex unison
|
||
|
||
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 @emph{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 @code{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 @code{org-publish-use-timestamps-flag} to @code{nil}, you gain the
|
||
main benefit of re-including any changed external files such as source
|
||
example files you might include with @samp{INCLUDE} keyword. The timestamp
|
||
mechanism in Org is not smart enough to detect if included files have
|
||
been modified.
|
||
|
||
@node Sample Configuration
|
||
@section 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.
|
||
@end menu
|
||
|
||
@node Simple example
|
||
@subsection Example: simple publishing configuration
|
||
|
||
This example publishes a set of Org files to the @samp{public_html}
|
||
directory on the local machine.
|
||
|
||
@lisp
|
||
(setq org-publish-project-alist
|
||
'(("org"
|
||
:base-directory "~/org/"
|
||
:publishing-directory "~/public_html"
|
||
:section-numbers nil
|
||
:table-of-contents nil
|
||
:style "<link rel=\"stylesheet\"
|
||
href=\"../other/mystyle.css\"
|
||
type=\"text/css\"/>")))
|
||
@end lisp
|
||
|
||
@node Complex example
|
||
@subsection 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 @samp{~/org/} and your
|
||
publishable images in @samp{~/images/}, you would link to an image with
|
||
|
||
@example
|
||
file:../images/myimage.png
|
||
@end example
|
||
|
||
On the web server, the relative path to the image should be the same.
|
||
You can accomplish this by setting up an @samp{images/} folder in the right
|
||
place on the web server, and publishing images to it.
|
||
|
||
@lisp
|
||
(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"))))
|
||
@end lisp
|
||
|
||
@node Triggering Publication
|
||
@section Triggering Publication
|
||
|
||
Once properly configured, Org can publish with the following commands:
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-e X} (@code{org-publish})
|
||
@kindex C-c C-e X
|
||
@findex org-publish
|
||
Prompt for a specific project and publish all files that belong
|
||
to it.
|
||
|
||
@item @kbd{C-c C-e P} (@code{org-publish-current-project})
|
||
@kindex C-c C-e P
|
||
@findex org-publish-current-project
|
||
Publish the project containing the current file.
|
||
|
||
@item @kbd{C-c C-e F} (@code{org-publish-current-file})
|
||
@kindex C-c C-e F
|
||
@findex org-publish-current-file
|
||
Publish only the current file.
|
||
|
||
@item @kbd{C-c C-e E} (@code{org-publish-all})
|
||
@kindex C-c C-e E
|
||
@findex org-publish-all
|
||
Publish every project.
|
||
@end table
|
||
|
||
@vindex org-publish-use-timestamps-flag
|
||
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
|
||
@code{org-publish-use-timestamps-flag}. This may be necessary in
|
||
particular if files include other files via @samp{SETUPFILE} or @samp{INCLUDE}
|
||
keywords.
|
||
|
||
@node Working with Source Code
|
||
@chapter Working with Source Code
|
||
|
||
@cindex source code, working with
|
||
|
||
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:
|
||
|
||
@example
|
||
#+BEGIN_SRC emacs-lisp
|
||
(defun org-xor (a b)
|
||
"Exclusive or."
|
||
(if a (not b) b))
|
||
#+END_SRC
|
||
@end example
|
||
|
||
Org can manage the source code in the block delimited by @samp{#+BEGIN_SRC}
|
||
@dots{} @samp{#+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 @emph{live code}
|
||
blocks because they can alter the content of the Org document or the
|
||
material that it exports. Users can control how live they want each
|
||
source code block by tweaking the header arguments (see @ref{Using Header Arguments}) for compiling, execution, extraction, and
|
||
exporting.
|
||
|
||
Source code blocks are one of many Org block types, which also include
|
||
@samp{quote}, @samp{export}, @samp{verse}, @samp{latex}, @samp{example}, and @samp{verbatim}. This
|
||
section pertains to blocks between @samp{#+BEGIN_SRC} and @samp{#+END_SRC}.
|
||
|
||
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 @emph{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 @emph{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.
|
||
|
||
Details of Org's facilities for working with source code are described
|
||
in the following sections.
|
||
|
||
@menu
|
||
* 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.
|
||
@end menu
|
||
|
||
@node Structure of Code Blocks
|
||
@section Structure of Code Blocks
|
||
|
||
@cindex code block, structure
|
||
@cindex source code, block structure
|
||
@cindex @samp{NAME} keyword, in source blocks
|
||
@cindex @samp{BEGIN_SRC}
|
||
|
||
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:
|
||
|
||
@example
|
||
#+NAME: <name>
|
||
#+BEGIN_SRC <language> <switches> <header arguments>
|
||
<body>
|
||
#+END_SRC
|
||
@end example
|
||
|
||
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
|
||
@ref{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.
|
||
|
||
@cindex source code, inline
|
||
An inline code block conforms to this structure:
|
||
|
||
@example
|
||
src_<language>@{<body>@}
|
||
@end example
|
||
|
||
@noindent
|
||
or
|
||
|
||
@example
|
||
src_<language>[<header arguments>]@{<body>@}
|
||
@end example
|
||
|
||
@table @asis
|
||
@item @samp{#+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 @ref{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.
|
||
|
||
@item @samp{#+BEGIN_SRC} @dots{} @samp{#+END_SRC}
|
||
Mandatory. They mark the start and end of a block that Org
|
||
requires. The @samp{#+BEGIN_SRC} line takes additional arguments, as
|
||
described next.
|
||
|
||
@item @samp{<language>}
|
||
@cindex language, in code blocks
|
||
Mandatory. It is the identifier of the source code language in
|
||
the block. See @ref{Languages}, for identifiers of supported
|
||
languages.
|
||
|
||
@item @samp{<switches>}
|
||
@cindex switches, in code blocks
|
||
Optional. Switches provide finer control of the code execution,
|
||
export, and format (see the discussion of switches in @ref{Literal Examples}).
|
||
|
||
@item @samp{<header arguments>}
|
||
@cindex header arguments, in code blocks
|
||
Optional. Heading arguments control many aspects of evaluation,
|
||
export and tangling of code blocks (see @ref{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.
|
||
|
||
@item @samp{<body>}
|
||
Source code in the dialect of the specified language identifier.
|
||
@end table
|
||
|
||
@node Using Header Arguments
|
||
@section 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.
|
||
|
||
@anchor{System-wide header arguments}
|
||
@subheading System-wide header arguments
|
||
|
||
@vindex org-babel-default-header-args
|
||
|
||
@vindex org-babel-default-header-args
|
||
System-wide values of header arguments can be specified by customizing
|
||
the @code{org-babel-default-header-args} variable, which defaults to the
|
||
following values:
|
||
|
||
@example
|
||
:session => "none"
|
||
:results => "replace"
|
||
:exports => "code"
|
||
:cache => "no"
|
||
:noweb => "no"
|
||
@end example
|
||
|
||
The example below sets @samp{:noweb} header arguments to @samp{yes}, which makes
|
||
Org expand @samp{:noweb} references by default.
|
||
|
||
@lisp
|
||
(setq org-babel-default-header-args
|
||
(cons '(:noweb . "yes")
|
||
(assq-delete-all :noweb org-babel-default-header-args)))
|
||
@end lisp
|
||
|
||
@cindex language specific default header arguments
|
||
@cindex default header arguments per language
|
||
Each language can have separate default header arguments by
|
||
customizing the variable @code{org-babel-default-header-args:<LANG>}, where
|
||
@var{<LANG>} is the name of the language. For details, see the
|
||
language-specific online documentation at
|
||
@uref{https://orgmode.org/worg/org-contrib/babel/}.
|
||
|
||
@anchor{Header arguments in Org mode properties}
|
||
@subheading Header arguments in Org mode properties
|
||
|
||
For header arguments applicable to the buffer, use @samp{PROPERTY} keyword
|
||
anywhere in the Org file (see @ref{Property Syntax}).
|
||
|
||
The following example makes all the R code blocks execute in the same
|
||
session. Setting @samp{:results} to @samp{silent} ignores the results of
|
||
executions for all blocks, not just R code blocks; no results inserted
|
||
for any block.
|
||
|
||
@example
|
||
#+PROPERTY: header-args:R :session *R*
|
||
#+PROPERTY: header-args :results silent
|
||
@end example
|
||
|
||
@vindex org-use-property-inheritance
|
||
Header arguments set through Org's property drawers (see @ref{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
|
||
@code{org-use-property-inheritance} setting.
|
||
|
||
In this example, @samp{:cache} defaults to @samp{yes} for all code blocks in the
|
||
sub-tree.
|
||
|
||
@example
|
||
* sample header
|
||
:PROPERTIES:
|
||
:header-args: :cache yes
|
||
:END:
|
||
@end example
|
||
|
||
@kindex C-c C-x p
|
||
@findex org-set-property
|
||
Properties defined through @code{org-set-property} function, bound to
|
||
@kbd{C-c C-x p}, apply to all active languages. They override
|
||
properties set in @code{org-babel-default-header-args}.
|
||
|
||
@cindex language specific header arguments properties
|
||
@cindex header arguments per language
|
||
Language-specific header arguments are also read from properties
|
||
@samp{header-args:<LANG>} where @var{<LANG>} is the language
|
||
identifier. For example,
|
||
|
||
@example
|
||
* Heading
|
||
:PROPERTIES:
|
||
:header-args:clojure: :session *clojure-1*
|
||
:header-args:R: :session *R*
|
||
:END:
|
||
** Subheading
|
||
:PROPERTIES:
|
||
:header-args:clojure: :session *clojure-2*
|
||
:END:
|
||
@end example
|
||
|
||
@noindent
|
||
would force separate sessions for Clojure blocks in @samp{Heading} and
|
||
@samp{Subheading}, but use the same session for all R blocks. Blocks in
|
||
@samp{Subheading} inherit settings from @samp{Heading}.
|
||
|
||
@anchor{Code block specific header arguments}
|
||
@subheading Code block specific header arguments
|
||
|
||
Header arguments are most commonly set at the source code block level,
|
||
on the @samp{#+BEGIN_SRC} line. Arguments set at this level take
|
||
precedence over those set in the @code{org-babel-default-header-args}
|
||
variable, and also those set as header properties.
|
||
|
||
In the following example, setting @samp{:results} to @samp{silent} makes it
|
||
ignore results of the code execution. Setting @samp{:exports} to @samp{code}
|
||
exports only the body of the code block to HTML or @LaTeX{}.
|
||
|
||
@example
|
||
#+NAME: factorial
|
||
#+BEGIN_SRC haskell :results silent :exports code :var n=0
|
||
fac 0 = 1
|
||
fac n = n * fac (n-1)
|
||
#+END_SRC
|
||
@end example
|
||
|
||
The same header arguments in an inline code block:
|
||
|
||
@example
|
||
src_haskell[:exports both]@{fac 5@}
|
||
@end example
|
||
|
||
@cindex @samp{HEADER}, keyword
|
||
Code block header arguments can span multiple lines using @samp{#+HEADER:}
|
||
on each line. Note that Org currently accepts the plural spelling of
|
||
@samp{#+HEADER:} only as a convenience for backward-compatibility. It may
|
||
be removed at some point.
|
||
|
||
Multi-line header arguments on an unnamed code block:
|
||
|
||
@example
|
||
#+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
|
||
@end example
|
||
|
||
Multi-line header arguments on a named code block:
|
||
|
||
@example
|
||
#+NAME: named-block
|
||
#+HEADER: :var data=2
|
||
#+BEGIN_SRC emacs-lisp
|
||
(message "data:%S" data)
|
||
#+END_SRC
|
||
|
||
#+RESULTS: named-block
|
||
: data:2
|
||
@end example
|
||
|
||
@anchor{Header arguments in function calls}
|
||
@subheading 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 @samp{#+CALL:} examples are shown below. For the complete
|
||
syntax of @samp{CALL} keyword, see @ref{Evaluating Code Blocks}.
|
||
|
||
In this example, @samp{:exports results} header argument is applied to the
|
||
evaluation of the @samp{#+CALL:} line.
|
||
|
||
@example
|
||
#+CALL: factorial(n=5) :exports results
|
||
@end example
|
||
|
||
In this example, @samp{:session special} header argument is applied to the
|
||
evaluation of @samp{factorial} code block.
|
||
|
||
@example
|
||
#+CALL: factorial[:session special](n=5)
|
||
@end example
|
||
|
||
@node Environment of a Code Block
|
||
@section Environment of a Code Block
|
||
|
||
|
||
|
||
@anchor{Passing arguments}
|
||
@subheading Passing arguments
|
||
|
||
@cindex passing arguments to code blocks
|
||
@cindex arguments, in code blocks
|
||
@cindex @samp{var}, header argument
|
||
Use @samp{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 @samp{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 @samp{var} header argument.
|
||
|
||
@example
|
||
:var NAME=ASSIGN
|
||
@end example
|
||
|
||
@noindent
|
||
@var{NAME} is the name of the variable bound in the code block
|
||
body. @var{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.
|
||
|
||
Here are examples of passing values by reference:
|
||
|
||
@table @asis
|
||
@item table
|
||
A table named with a @samp{NAME} keyword.
|
||
|
||
@example
|
||
#+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
|
||
@end example
|
||
|
||
When passing a table, you can treat specially the row, or the
|
||
column, containing labels for the columns, or the rows, in the
|
||
table.
|
||
|
||
@cindex @samp{colnames}, header argument
|
||
The @samp{colnames} header argument accepts @samp{yes}, @samp{no}, or @samp{nil}
|
||
values. The default value is @samp{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 @samp{yes}, Org does the same to the first row, even if the
|
||
initial table does not contain any horizontal rule. When set to
|
||
@samp{no}, Org does not pre-process column names at all.
|
||
|
||
@example
|
||
#+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* |
|
||
@end example
|
||
|
||
@cindex @samp{rownames}, header argument
|
||
Similarly, the @samp{rownames} header argument can take two values:
|
||
@samp{yes} or @samp{no}. When set to @samp{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 @samp{no}, which means
|
||
Org does not pre-process the first column. Note that Emacs Lisp
|
||
code blocks ignore @samp{rownames} header argument because of the ease
|
||
of table-handling in Emacs.
|
||
|
||
@example
|
||
#+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 |
|
||
@end example
|
||
|
||
@item list
|
||
A simple named list.
|
||
|
||
@example
|
||
#+NAME: example-list
|
||
- simple
|
||
- not
|
||
- nested
|
||
- list
|
||
|
||
#+BEGIN_SRC emacs-lisp :var x=example-list
|
||
(print x)
|
||
#+END_SRC
|
||
|
||
#+RESULTS:
|
||
| simple | list |
|
||
@end example
|
||
|
||
Note that only the top level list items are passed along. Nested
|
||
list items are ignored.
|
||
|
||
@item code block without arguments
|
||
A code block name, as assigned by @samp{NAME} keyword from the example
|
||
above, optionally followed by parentheses.
|
||
|
||
@example
|
||
#+BEGIN_SRC emacs-lisp :var length=table-length()
|
||
(* 2 length)
|
||
#+END_SRC
|
||
|
||
#+RESULTS:
|
||
: 8
|
||
@end example
|
||
|
||
@item code block with arguments
|
||
A code block name, as assigned by @samp{NAME} keyword, followed by
|
||
parentheses and optional arguments passed within the parentheses.
|
||
|
||
@example
|
||
#+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
|
||
@end example
|
||
|
||
@item literal example
|
||
A literal example block named with a @samp{NAME} keyword.
|
||
|
||
@example
|
||
#+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.
|
||
@end example
|
||
@end table
|
||
|
||
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
|
||
@emph{before} other table-related header arguments are applied, such as
|
||
@samp{hlines}, @samp{colnames} and @samp{rownames}. The following example assigns
|
||
the last cell of the first row the table @samp{example-table} to the
|
||
variable @samp{data}:
|
||
|
||
@example
|
||
#+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
|
||
@end example
|
||
|
||
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 @samp{example-table}
|
||
to @samp{data}.
|
||
|
||
@example
|
||
#+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 |
|
||
@end example
|
||
|
||
To pick the entire range, use an empty index, or the single character
|
||
@samp{*}. @samp{0:-1} does the same thing. Example below shows how to
|
||
reference the first column only.
|
||
|
||
@example
|
||
#+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 |
|
||
@end example
|
||
|
||
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.
|
||
|
||
@example
|
||
#+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 |
|
||
@end example
|
||
|
||
Note that row names and column names are not removed prior to variable
|
||
indexing. You need to take them into account, even when @samp{colnames} or
|
||
@samp{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 @samp{(}, @samp{[}, @samp{'} or @samp{`} 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.
|
||
|
||
@example
|
||
#+BEGIN_SRC sh :var filename=(buffer-file-name) :exports both
|
||
wc -w $filename
|
||
#+END_SRC
|
||
@end example
|
||
|
||
Note that values read from tables and lists are not mistakenly
|
||
evaluated as Emacs Lisp code, as illustrated in the following example.
|
||
|
||
@example
|
||
#+NAME: table
|
||
| (a b c) |
|
||
|
||
#+HEADER: :var data=table[0,0]
|
||
#+BEGIN_SRC perl
|
||
$data
|
||
#+END_SRC
|
||
|
||
#+RESULTS:
|
||
: (a b c)
|
||
@end example
|
||
|
||
@anchor{Using sessions}
|
||
@subheading Using sessions
|
||
|
||
@cindex using sessions in code blocks
|
||
@cindex @samp{session}, header argument
|
||
Two code blocks can share the same environment. The @samp{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.
|
||
|
||
@table @asis
|
||
@item @samp{none}
|
||
Default. Each code block gets a new interpreter process to
|
||
execute. The process terminates once the block is evaluated.
|
||
|
||
@item @var{STRING}
|
||
Any string besides @samp{none} turns that string into the name of that
|
||
session. For example, @samp{:session STRING} names it @samp{STRING}. If
|
||
@samp{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.
|
||
@end table
|
||
|
||
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.
|
||
|
||
@anchor{Choosing a working directory}
|
||
@subheading Choosing a working directory
|
||
|
||
@cindex working directory, in a code block
|
||
@cindex @samp{dir}, header argument
|
||
The @samp{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 @samp{:dir PATH}
|
||
temporarily has the same effect as changing the current directory with
|
||
@kbd{M-x cd PATH}, and then not setting @samp{dir}. Under the
|
||
surface, @samp{dir} simply sets the value of the Emacs variable
|
||
@code{default-directory}.
|
||
|
||
For example, to save the plot file in the @samp{Work/} folder of the home
|
||
directory---notice tilde is expanded:
|
||
|
||
@example
|
||
#+BEGIN_SRC R :file myplot.png :dir ~/Work
|
||
matplot(matrix(rnorm(100), 10), type="l")
|
||
#+END_SRC
|
||
@end example
|
||
|
||
To evaluate the code block on a remote machine, supply a remote
|
||
directory name using Tramp syntax. For example:
|
||
|
||
@example
|
||
#+BEGIN_SRC R :file plot.png :dir /scp:dand@@yakuba.princeton.edu:
|
||
plot(1:10, main=system("hostname", intern=TRUE))
|
||
#+END_SRC
|
||
@end example
|
||
|
||
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
|
||
@samp{dir} and @code{default-directory}, as illustrated here:
|
||
|
||
@example
|
||
[[file:/scp:dand@@yakuba.princeton.edu:/home/dand/plot.png][plot.png]]
|
||
@end example
|
||
|
||
When @samp{dir} is used with @samp{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 @samp{dir} with @samp{:exports results} or with @samp{:exports both} to
|
||
avoid Org inserting incorrect links to remote files. That is because
|
||
Org does not expand @code{default directory} to avoid some underlying
|
||
portability issues.
|
||
|
||
@anchor{Inserting headers and footers}
|
||
@subheading Inserting headers and footers
|
||
|
||
@cindex headers, in code blocks
|
||
@cindex footers, in code blocks
|
||
@cindex @samp{prologue}, header argument
|
||
The @samp{prologue} header argument is for appending to the top of the code
|
||
block for execution, like a reset instruction. For example, you may
|
||
use @samp{:prologue "reset"} in a Gnuplot code block or, for every such
|
||
block:
|
||
|
||
@lisp
|
||
(add-to-list 'org-babel-default-header-args:gnuplot
|
||
'((:prologue . "reset")))
|
||
|
||
@end lisp
|
||
|
||
@cindex @samp{epilogue}, header argument
|
||
Likewise, the value of the @samp{epilogue} header argument is for appending
|
||
to the end of the code block for execution.
|
||
|
||
@node Evaluating Code Blocks
|
||
@section Evaluating Code Blocks
|
||
|
||
@cindex code block, evaluating
|
||
@cindex source code, evaluating
|
||
@cindex @samp{RESULTS}, keyword
|
||
|
||
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 @ref{Code Evaluation Security}.
|
||
|
||
@anchor{How to evaluate source code}
|
||
@subheading 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 @samp{RESULTS} keyword. Org creates the @samp{RESULTS}
|
||
keyword if one is not already there.
|
||
|
||
By default, Org enables only Emacs Lisp code blocks for execution.
|
||
See @ref{Languages} to enable other languages.
|
||
|
||
@kindex C-c C-c
|
||
@kindex C-c C-v e
|
||
@findex org-babel-execute-src-block
|
||
Org provides many ways to execute code blocks. @kbd{C-c C-c} or
|
||
@kbd{C-c C-v e} with the point on a code block@footnote{The option @code{org-babel-no-eval-on-ctrl-c-ctrl-c} can be used
|
||
to remove code evaluation from the @kbd{C-c C-c} key binding.} calls the
|
||
@code{org-babel-execute-src-block} function, which executes the code in the
|
||
block, collects the results, and inserts them in the buffer.
|
||
|
||
@cindex @samp{CALL}, keyword
|
||
@vindex org-babel-inline-result-wrap
|
||
By calling a named code block@footnote{Actually, the constructs @samp{call_<name>()} and @samp{src_<lang>@{@}}
|
||
are not evaluated when they appear in a keyword line---i.e. lines
|
||
starting with @samp{#+KEYWORD:}, see @ref{In-buffer Settings}.} 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 @ref{Library of Babel}).
|
||
|
||
The syntax for @samp{CALL} keyword is:
|
||
|
||
@example
|
||
#+CALL: <name>(<arguments>)
|
||
#+CALL: <name>[<inside header arguments>](<arguments>) <end header arguments>
|
||
@end example
|
||
|
||
The syntax for inline named code blocks is:
|
||
|
||
@example
|
||
... call_<name>(<arguments>) ...
|
||
... call_<name>[<inside header arguments>](<arguments>)[<end header arguments>] ...
|
||
@end example
|
||
|
||
When inline syntax is used, the result is wrapped based on the
|
||
variable @code{org-babel-inline-result-wrap}, which by default is set to
|
||
@code{"=%s="} to produce verbatim text suitable for markup.
|
||
|
||
@table @asis
|
||
@item @samp{<name>}
|
||
This is the name of the code block (see @ref{Structure of Code Blocks}) to be evaluated in the current document. If the block is
|
||
located in another file, start @samp{<name>} with the file name
|
||
followed by a colon. For example, in order to execute a block
|
||
named @samp{clear-data} in @samp{file.org}, you can write the following:
|
||
|
||
@example
|
||
#+CALL: file.org:clear-data()
|
||
@end example
|
||
|
||
@item @samp{<arguments>}
|
||
Org passes arguments to the code block using standard function
|
||
call syntax. For example, a @samp{#+CALL:} line that passes @samp{4} to
|
||
a code block named @samp{double}, which declares the header argument
|
||
@samp{:var n=2}, would be written as:
|
||
|
||
@example
|
||
#+CALL: double(n=4)
|
||
@end example
|
||
|
||
@noindent
|
||
Note how this function call syntax is different from the header
|
||
argument syntax.
|
||
|
||
@item @samp{<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, @samp{[: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.
|
||
|
||
@item @samp{<end header arguments>}
|
||
End header arguments affect the results returned by the code
|
||
block. For example, @samp{:results html} wraps the results in
|
||
a @samp{#+BEGIN_EXPORT html} block before inserting the results in the
|
||
Org buffer.
|
||
@end table
|
||
|
||
@anchor{Limit code block evaluation}
|
||
@subheading Limit code block evaluation
|
||
|
||
@cindex @samp{eval}, header argument
|
||
@cindex control code block evaluation
|
||
The @samp{eval} header argument can limit evaluation of specific code
|
||
blocks and @samp{CALL} keyword. It is useful for protection against
|
||
evaluating untrusted code blocks by prompting for a confirmation.
|
||
|
||
@table @asis
|
||
@item @samp{never} or @samp{no}
|
||
Org never evaluates the source code.
|
||
|
||
@item @samp{query}
|
||
Org prompts the user for permission to evaluate the source code.
|
||
|
||
@item @samp{never-export} or @samp{no-export}
|
||
Org does not evaluate the source code when exporting, yet the
|
||
user can evaluate it interactively.
|
||
|
||
@item @samp{query-export}
|
||
Org prompts the user for permission to evaluate the source code
|
||
during export.
|
||
@end table
|
||
|
||
If @samp{eval} header argument is not set, then Org determines whether to
|
||
evaluate the source code from the @code{org-confirm-babel-evaluate}
|
||
variable (see @ref{Code Evaluation Security}).
|
||
|
||
@anchor{Cache results of evaluation}
|
||
@subheading Cache results of evaluation
|
||
|
||
@cindex @samp{cache}, header argument
|
||
@cindex cache results of code evaluation
|
||
The @samp{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 @samp{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 @ref{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 @samp{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 @ref{Noweb Reference Syntax}). For
|
||
reasons why, see @uref{http://thread.gmane.org/gmane.emacs.orgmode/79046}.
|
||
|
||
The @samp{cache} header argument can have one of two values: @samp{yes} or @samp{no}.
|
||
|
||
@table @asis
|
||
@item @samp{no}
|
||
Default. No caching of results; code block evaluated every
|
||
time.
|
||
|
||
@item @samp{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 @samp{#+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 @samp{#+RESULTS:} line.
|
||
@end table
|
||
|
||
In this example, both functions are cached. But @samp{caller} runs only if
|
||
the result from @samp{random} has changed since the last run.
|
||
|
||
@example
|
||
#+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
|
||
@end example
|
||
|
||
@node Results of Evaluation
|
||
@section Results of Evaluation
|
||
|
||
@cindex code block, results of evaluation
|
||
@cindex source code, results of evaluation
|
||
|
||
@cindex @samp{results}, header argument
|
||
How Org handles results of a code block execution depends on many
|
||
header arguments working together. The primary determinant, however,
|
||
is the @samp{results} header argument. It accepts four classes of options.
|
||
Each code block can take only one option per class:
|
||
|
||
@table @asis
|
||
@item collection
|
||
For how the results should be collected from the code block;
|
||
|
||
@item type
|
||
For which type of result the code block will return; affects how
|
||
Org processes and inserts results in the Org buffer;
|
||
|
||
@item format
|
||
For the result; affects how Org processes and inserts results in
|
||
the Org buffer;
|
||
|
||
@item handling
|
||
For processing results after evaluation of the code block;
|
||
@end table
|
||
|
||
@anchor{Collection}
|
||
@subheading Collection
|
||
|
||
Collection options specify the results. Choose one of the options;
|
||
they are mutually exclusive.
|
||
|
||
@table @asis
|
||
@item @samp{value}
|
||
Default. 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 @samp{:results value}, code should
|
||
execute like a function and return a value. For languages like
|
||
Python, an explicit @code{return} statement is mandatory when using
|
||
@samp{:results value}. Result is the value returned by the last
|
||
statement in the code block.
|
||
|
||
When evaluating the code block in a session (see @ref{Environment of a Code Block}), Org passes the code to an interpreter running as
|
||
an 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 @code{_} in Python and Ruby, and the value of
|
||
@code{.Last.value} in R.
|
||
|
||
@item @samp{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.
|
||
|
||
Note that this collection is not the same as that would be
|
||
collected from stdout of a non-interactive interpreter running as
|
||
an external process. Compare for example these two blocks:
|
||
|
||
@example
|
||
#+BEGIN_SRC python :results output
|
||
print "hello"
|
||
2
|
||
print "bye"
|
||
#+END_SRC
|
||
|
||
#+RESULTS:
|
||
: hello
|
||
: bye
|
||
@end example
|
||
|
||
In the above non-session mode, the ``2'' is not printed; so it does
|
||
not appear in results.
|
||
|
||
@example
|
||
#+BEGIN_SRC python :results output :session
|
||
print "hello"
|
||
2
|
||
print "bye"
|
||
#+END_SRC
|
||
|
||
#+RESULTS:
|
||
: hello
|
||
: 2
|
||
: bye
|
||
@end example
|
||
|
||
In the above session, the interactive interpreter receives and
|
||
prints ``2''. Results show that.
|
||
@end table
|
||
|
||
@anchor{Type}
|
||
@subheading 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 @asis
|
||
@item @samp{table}
|
||
@itemx @samp{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: @samp{:results value table}.
|
||
|
||
@cindex @samp{hlines}, header argument
|
||
In-between each table row or below the table headings, sometimes
|
||
results have horizontal lines, which are also known as ``hlines''.
|
||
The @samp{hlines} argument with the default @samp{no} value strips such
|
||
lines from the input table. For most code, this is desirable, or
|
||
else those @samp{hline} symbols raise unbound variable errors.
|
||
A @samp{yes} accepts such lines, as demonstrated in the following
|
||
example.
|
||
|
||
@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 |
|
||
@end example
|
||
|
||
@item @samp{list}
|
||
Interpret the results as an Org list. If the result is a single
|
||
value, create a list of one element.
|
||
|
||
@item @samp{scalar}
|
||
@itemx @samp{verbatim}
|
||
Interpret literally and insert as quoted text. Do not create
|
||
a table. Usage example: @samp{:results value verbatim}.
|
||
|
||
@item @samp{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.
|
||
|
||
@cindex @samp{file}, header argument
|
||
@cindex @samp{output-dir}, header argument
|
||
Org first tries to generate the filename from the value of the
|
||
@samp{file} header argument and the directory specified using the
|
||
@samp{output-dir} header arguments. If @samp{output-dir} is not specified,
|
||
Org assumes it is the current directory.
|
||
|
||
@example
|
||
#+BEGIN_SRC asymptote :results value file :file circle.pdf :output-dir img/
|
||
size(2cm);
|
||
draw(unitcircle);
|
||
#+END_SRC
|
||
@end example
|
||
|
||
@cindex @samp{file-ext}, header argument
|
||
If @samp{file} is missing, Org generates the base name of the output
|
||
file from the name of the code block, and its extension from the
|
||
@samp{file-ext} header argument. In that case, both the name and the
|
||
extension are mandatory.
|
||
|
||
@example
|
||
#+name: circle
|
||
#+BEGIN_SRC asymptote :results value file :file-ext pdf
|
||
size(2cm);
|
||
draw(unitcircle);
|
||
#+END_SRC
|
||
@end example
|
||
|
||
@cindex @samp{file-desc}, header argument
|
||
The @samp{file-desc} header argument defines the description (see
|
||
@ref{Link Format}) for the link. If @samp{file-desc} has no value, Org
|
||
uses the generated file name for both the ``link'' and
|
||
``description'' parts of the link.
|
||
@end table
|
||
|
||
@anchor{Format}
|
||
@subheading 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.
|
||
|
||
@table @asis
|
||
@item @samp{code}
|
||
Result enclosed in a code block. Useful for parsing. Usage
|
||
example: @samp{:results value code}.
|
||
|
||
@item @samp{drawer}
|
||
Result wrapped in a @samp{RESULTS} drawer. Useful for containing
|
||
@samp{raw} or @samp{org} results for later scripting and automated
|
||
processing. Usage example: @samp{:results value drawer}.
|
||
|
||
@item @samp{html}
|
||
Results enclosed in a @samp{BEGIN_EXPORT html} block. Usage example:
|
||
@samp{:results value html}.
|
||
|
||
@item @samp{latex}
|
||
Results enclosed in a @samp{BEGIN_EXPORT latex} block. Usage example:
|
||
@samp{:results value latex}.
|
||
|
||
@item @samp{link}
|
||
@itemx @samp{graphics}
|
||
Result is a link to the file specified in @samp{:file} header
|
||
argument. However, unlike plain @samp{:file}, nothing is written to
|
||
the disk. The block is used for its side-effects only, as in the
|
||
following example:
|
||
|
||
@example
|
||
#+begin_src shell :results link :file "download.tar.gz"
|
||
wget -c "http://example.com/download.tar.gz"
|
||
#+end_src
|
||
@end example
|
||
|
||
@item @samp{org}
|
||
Results enclosed in a @samp{BEGIN_SRC org} block. For comma-escape,
|
||
either @kbd{@key{TAB}} in the block, or export the file. Usage
|
||
example: @samp{:results value org}.
|
||
|
||
@item @samp{pp}
|
||
Result converted to pretty-print source code. Enclosed in a code
|
||
block. Languages supported: Emacs Lisp, Python, and Ruby. Usage
|
||
example: @samp{:results value pp}.
|
||
|
||
@item @samp{raw}
|
||
Interpreted as raw Org mode. Inserted directly into the buffer.
|
||
Aligned if it is a table. Usage example: @samp{:results value raw}.
|
||
@end table
|
||
|
||
@anchor{Handling}
|
||
@subheading Handling
|
||
|
||
Handling options after collecting the results.
|
||
|
||
@table @asis
|
||
@item @samp{silent}
|
||
Do not insert results in the Org mode buffer, but echo them in
|
||
the minibuffer. Usage example: @samp{:results output silent}.
|
||
|
||
@item @samp{replace}
|
||
Default. Insert results in the Org buffer. Remove previous
|
||
results. Usage example: @samp{:results output replace}.
|
||
|
||
@item @samp{append}
|
||
Append results to the Org buffer. Latest results are at the
|
||
bottom. Does not remove previous results. Usage example:
|
||
@samp{:results output append}.
|
||
|
||
@item @samp{prepend}
|
||
Prepend results to the Org buffer. Latest results are at the
|
||
top. Does not remove previous results. Usage example: @samp{:results
|
||
output prepend}.
|
||
@end table
|
||
|
||
@anchor{Post-processing}
|
||
@subheading Post-processing
|
||
|
||
@cindex @samp{post}, header argument
|
||
@cindex @samp{*this*}, in @samp{post} header argument
|
||
The @samp{post} header argument is for post-processing results from block
|
||
evaluation. When @samp{post} has any value, Org binds the results to
|
||
@code{*this*} variable for easy passing to @samp{var} header argument
|
||
specifications (see @ref{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 @samp{post} header argument in
|
||
action. The first one shows how to attach an @samp{ATTR_LATEX} keyword
|
||
using @samp{post}.
|
||
|
||
@example
|
||
#+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:
|
||
@end example
|
||
|
||
The second example shows use of @samp{colnames} header argument in @samp{post}
|
||
to pass data between code blocks.
|
||
|
||
@example
|
||
#+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 |
|
||
@end example
|
||
|
||
@node Exporting Code Blocks
|
||
@section Exporting Code Blocks
|
||
|
||
@cindex code block, exporting
|
||
@cindex source code, exporting
|
||
|
||
It is possible to export the @emph{code} of code blocks, the @emph{results} of
|
||
code block evaluation, @emph{both} the code and the results of code block
|
||
evaluation, or @emph{none}. Org defaults to exporting @emph{code} for most
|
||
languages. For some languages, such as ditaa, Org defaults to
|
||
@emph{results}. To export just the body of code blocks, see @ref{Literal Examples}. To selectively export sub-trees of an Org document, see
|
||
@ref{Exporting}.
|
||
|
||
@cindex @samp{export}, header argument
|
||
The @samp{exports} header argument is to specify if that part of the Org
|
||
file is exported to, say, HTML or @LaTeX{} formats.
|
||
|
||
@table @asis
|
||
@item @samp{code}
|
||
The default. The body of code is included into the exported
|
||
file. Example: @samp{:exports code}.
|
||
|
||
@item @samp{results}
|
||
The results of evaluation of the code is included in the exported
|
||
file. Example: @samp{:exports results}.
|
||
|
||
@item @samp{both}
|
||
Both the code and results of evaluation are included in the
|
||
exported file. Example: @samp{:exports both}.
|
||
|
||
@item @samp{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: @samp{:exports none}.
|
||
@end table
|
||
|
||
@vindex org-export-use-babel
|
||
To stop Org from evaluating code blocks to speed exports, use the
|
||
header argument @samp{:eval never-export} (see @ref{Evaluating Code Blocks}).
|
||
To stop Org from evaluating code blocks for greater security, set the
|
||
@code{org-export-use-babel} variable to @code{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 @samp{:eval never-export} (see @ref{Evaluating Code Blocks}).
|
||
|
||
Org never evaluates code blocks in commented sub-trees when exporting
|
||
(see @ref{Comment Lines}). On the other hand, Org does evaluate code
|
||
blocks in sub-trees excluded from export (see @ref{Export Settings}).
|
||
|
||
@node Extracting Source Code
|
||
@section Extracting Source Code
|
||
|
||
@cindex tangling
|
||
@cindex source code, extracting
|
||
@cindex code block, 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 @emph{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 @ref{Noweb Reference Syntax}).
|
||
|
||
@anchor{Header arguments}
|
||
@subheading Header arguments
|
||
|
||
@cindex @samp{tangle}, header argument
|
||
The @samp{tangle} header argument specifies if the code block is exported
|
||
to source file(s).
|
||
|
||
@table @asis
|
||
@item @samp{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: @samp{:tangle yes}.
|
||
|
||
@item @samp{no}
|
||
The default. Do not extract the code in a source code file.
|
||
Example: @samp{:tangle no}.
|
||
|
||
@item @var{FILENAME}
|
||
Export the code block to source file whose file name is derived
|
||
from any string passed to the @samp{tangle} header argument. Org
|
||
derives the file name as being relative to the directory of the
|
||
Org file's location. Example: @samp{:tangle FILENAME}.
|
||
@end table
|
||
|
||
@cindex @samp{mkdirp}, header argument
|
||
The @samp{mkdirp} header argument creates parent directories for tangled
|
||
files if the directory does not exist. @samp{yes} enables directory
|
||
creation and @samp{no} inhibits directory creation.
|
||
|
||
@cindex @samp{comments}, header argument
|
||
The @samp{comments} header argument controls inserting comments into
|
||
tangled files. These are above and beyond whatever comments may
|
||
already exist in the code block.
|
||
|
||
@table @asis
|
||
@item @samp{no}
|
||
The default. Do not insert any extra comments during tangling.
|
||
|
||
@item @samp{link}
|
||
Wrap the code block in comments. Include links pointing back to
|
||
the place in the Org file from where the code was tangled.
|
||
|
||
@item @samp{yes}
|
||
Kept for backward compatibility; same as @samp{link}.
|
||
|
||
@item @samp{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.
|
||
|
||
@item @samp{both}
|
||
Includes both @samp{link} and @samp{org} options.
|
||
|
||
@item @samp{noweb}
|
||
Includes @samp{link} option, expands Noweb references (see @ref{Noweb Reference Syntax}), and wraps them in link comments inside the
|
||
body of the code block.
|
||
@end table
|
||
|
||
@cindex @samp{padline}, header argument
|
||
The @samp{padline} header argument controls insertion of newlines to pad
|
||
source code in the tangled file.
|
||
|
||
@table @asis
|
||
@item @samp{yes}
|
||
Default. Insert a newline before and after each code block in
|
||
the tangled file.
|
||
|
||
@item @samp{no}
|
||
Do not insert newlines to pad the tangled code blocks.
|
||
@end table
|
||
|
||
@cindex @samp{shebang}, header argument
|
||
The @samp{shebang} header argument can turn results into executable script
|
||
files. By setting it to a string value---for example, @samp{: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.
|
||
|
||
@cindex @samp{no-expand}, header argument
|
||
By default Org expands code blocks during tangling. The @samp{no-expand}
|
||
header argument turns off such expansions. Note that one side-effect
|
||
of expansion by @code{org-babel-expand-src-block} also assigns values (see
|
||
@ref{Environment of a Code Block}) to variables. Expansions also replace
|
||
Noweb references with their targets (see @ref{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.
|
||
|
||
@anchor{Functions}
|
||
@subheading Functions
|
||
|
||
@table @asis
|
||
@item @code{org-babel-tangle}
|
||
@findex org-babel-tangle
|
||
@kindex C-c C-v t
|
||
Tangle the current file. Bound to @kbd{C-c C-v t}.
|
||
|
||
With prefix argument only tangle the current code block.
|
||
|
||
@item @code{org-babel-tangle-file}
|
||
@findex org-babel-tangle-file
|
||
@kindex C-c C-v f
|
||
Choose a file to tangle. Bound to @kbd{C-c C-v f}.
|
||
@end table
|
||
|
||
@anchor{Hooks (1)}
|
||
@subheading Hooks
|
||
|
||
@table @asis
|
||
@item @code{org-babel-post-tangle-hook}
|
||
@vindex org-babel-post-tangle-hook
|
||
This hook is run from within code files tangled by
|
||
@code{org-babel-tangle}, making it suitable for post-processing,
|
||
compilation, and evaluation of code in the tangled files.
|
||
@end table
|
||
|
||
@anchor{Jumping between code and Org}
|
||
@subheading Jumping between code and Org
|
||
|
||
@findex org-babel-tangle-jump-to-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
|
||
@code{org-babel-tangle-jump-to-org} function with two additional source
|
||
code block header arguments:
|
||
|
||
@enumerate
|
||
@item
|
||
Set @samp{padline} to true---this is the default setting.
|
||
@item
|
||
Set @samp{comments} to @samp{link}, which makes Org insert links to the Org
|
||
file.
|
||
@end enumerate
|
||
|
||
@node Languages
|
||
@section Languages
|
||
|
||
@cindex babel, languages
|
||
@cindex source code, languages
|
||
@cindex code block, languages
|
||
|
||
Code blocks in the following languages are supported.
|
||
|
||
@multitable {aaaaaaaaaa} {aaaaaaaaaa} {aaaaaaaaaaaaaa} {aaaaaaaaaa}
|
||
@headitem Language
|
||
@tab Identifier
|
||
@tab Language
|
||
@tab Identifier
|
||
@item Asymptote
|
||
@tab asymptote
|
||
@tab Awk
|
||
@tab awk
|
||
@item C
|
||
@tab C
|
||
@tab C++
|
||
@tab C++
|
||
@item Clojure
|
||
@tab clojure
|
||
@tab CSS
|
||
@tab css
|
||
@item D
|
||
@tab d
|
||
@tab ditaa
|
||
@tab ditaa
|
||
@item Graphviz
|
||
@tab dot
|
||
@tab Emacs Calc
|
||
@tab calc
|
||
@item Emacs Lisp
|
||
@tab emacs-lisp
|
||
@tab Fortran
|
||
@tab fortran
|
||
@item Gnuplot
|
||
@tab gnuplot
|
||
@tab Haskell
|
||
@tab haskell
|
||
@item Java
|
||
@tab java
|
||
@tab Javascript
|
||
@tab js
|
||
@item @LaTeX{}
|
||
@tab latex
|
||
@tab Ledger
|
||
@tab ledger
|
||
@item Lisp
|
||
@tab lisp
|
||
@tab Lilypond
|
||
@tab lilypond
|
||
@item Lua
|
||
@tab lua
|
||
@tab MATLAB
|
||
@tab matlab
|
||
@item Mscgen
|
||
@tab mscgen
|
||
@tab Objective Caml
|
||
@tab ocaml
|
||
@item Octave
|
||
@tab octave
|
||
@tab Org mode
|
||
@tab org
|
||
@item Oz
|
||
@tab oz
|
||
@tab Perl
|
||
@tab perl
|
||
@item Plantuml
|
||
@tab plantuml
|
||
@tab Processing.js
|
||
@tab processing
|
||
@item Python
|
||
@tab python
|
||
@tab R
|
||
@tab R
|
||
@item Ruby
|
||
@tab ruby
|
||
@tab Sass
|
||
@tab sass
|
||
@item Scheme
|
||
@tab scheme
|
||
@tab GNU Screen
|
||
@tab screen
|
||
@item Sed
|
||
@tab sed
|
||
@tab shell
|
||
@tab sh
|
||
@item SQL
|
||
@tab sql
|
||
@tab SQLite
|
||
@tab sqlite
|
||
@item Vala
|
||
@tab vala
|
||
@tab
|
||
@tab
|
||
@end multitable
|
||
|
||
Additional documentation for some languages is at
|
||
@uref{https://orgmode.org/worg/org-contrib/babel/languages.html}.
|
||
|
||
@vindex org-babel-load-languages
|
||
By default, only Emacs Lisp is enabled for evaluation. To enable or
|
||
disable other languages, customize the @code{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.
|
||
|
||
@lisp
|
||
(org-babel-do-load-languages
|
||
'org-babel-load-languages
|
||
'((emacs-lisp . nil)
|
||
(R . t)))
|
||
@end lisp
|
||
|
||
Note that this is not the only way to enable a language. Org also
|
||
enables languages when loaded with @code{require} statement. For example,
|
||
the following enables execution of Clojure code blocks:
|
||
|
||
@lisp
|
||
(require 'ob-clojure)
|
||
@end lisp
|
||
|
||
@node Editing Source Code
|
||
@section Editing Source Code
|
||
|
||
@cindex code block, editing
|
||
@cindex source code, editing
|
||
|
||
@kindex C-c '
|
||
Use @kbd{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 @kbd{C-c '} again to close the buffer
|
||
and return to the Org buffer.
|
||
|
||
@kindex C-x C-s
|
||
@vindex org-edit-src-auto-save-idle-delay
|
||
@cindex auto-save, in code block editing
|
||
@kbd{C-x C-s} saves the buffer and updates the contents of the
|
||
Org buffer. Set @code{org-edit-src-auto-save-idle-delay} to save the base
|
||
buffer after a certain idle delay time. Set
|
||
@code{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 @code{org-edit-structure}.
|
||
|
||
@table @asis
|
||
@item @code{org-src-lang-modes}
|
||
@vindex org-src-lang-modes
|
||
If an Emacs major-mode named @code{<LANG>-mode} exists, where
|
||
@var{<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.
|
||
|
||
@item @code{org-src-window-setup}
|
||
@vindex org-src-window-setup
|
||
For specifying Emacs window arrangement when the new edit buffer
|
||
is created.
|
||
|
||
@item @code{org-src-preserve-indentation}
|
||
@cindex indentation, in code blocks
|
||
@vindex org-src-preserve-indentation
|
||
Default is @code{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-@code{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.
|
||
|
||
@item @code{org-src-ask-before-returning-to-edit-buffer}
|
||
@vindex org-src-ask-before-returning-to-edit-buffer
|
||
When @code{nil}, Org returns to the edit buffer without further
|
||
prompts. The default prompts for a confirmation.
|
||
@end table
|
||
|
||
@vindex org-src-fontify-natively
|
||
@vindex org-src-block-faces
|
||
Set @code{org-src-fontify-natively} to non-@code{nil} to turn on native code
|
||
fontification in the @emph{Org} buffer. Fontification of code blocks can
|
||
give visual separation of text and code on the display page. To
|
||
further customize the appearance of @code{org-block} for specific
|
||
languages, customize @code{org-src-block-faces}. The following example
|
||
shades the background of regular blocks, and colors source blocks only
|
||
for Python and Emacs Lisp languages.
|
||
|
||
@lisp
|
||
(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"))))
|
||
@end lisp
|
||
|
||
@node Noweb Reference Syntax
|
||
@section Noweb Reference Syntax
|
||
|
||
@cindex code block, Noweb reference
|
||
@cindex syntax, Noweb
|
||
@cindex source code, Noweb reference
|
||
|
||
Org supports named blocks in Noweb@footnote{For Noweb literate programming details, see
|
||
@uref{http://www.cs.tufts.edu/~nr/noweb/}.} style syntax:
|
||
|
||
@example
|
||
<<CODE-BLOCK-ID>>
|
||
@end example
|
||
|
||
Org can replace the construct with the source code, or the results of
|
||
evaluation, of the code block identified as @var{CODE-BLOCK-ID}.
|
||
|
||
@cindex @samp{noweb}, header argument
|
||
The @samp{noweb} header argument controls expansion of Noweb syntax
|
||
references. Expansions occur when source code blocks are evaluated,
|
||
tangled, or exported.
|
||
|
||
@table @asis
|
||
@item @samp{no}
|
||
Default. No expansion of Noweb syntax references in the body of
|
||
the code when evaluating, tangling, or exporting.
|
||
|
||
@item @samp{yes}
|
||
Expansion of Noweb syntax references in the body of the code
|
||
block when evaluating, tangling, or exporting.
|
||
|
||
@item @samp{tangle}
|
||
Expansion of Noweb syntax references in the body of the code
|
||
block when tangling. No expansion when evaluating or exporting.
|
||
|
||
@item @samp{no-export}
|
||
Expansion of Noweb syntax references in the body of the code
|
||
block when evaluating or tangling. No expansion when exporting.
|
||
|
||
@item @samp{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.
|
||
|
||
@item @samp{eval}
|
||
Expansion of Noweb syntax references in the body of the code
|
||
block only before evaluating.
|
||
@end table
|
||
|
||
In the following example,
|
||
|
||
@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
|
||
@end example
|
||
|
||
@noindent
|
||
the second code block is expanded as
|
||
|
||
@example
|
||
#+BEGIN_SRC emacs-lisp :noweb yes
|
||
(setq sentence "Never a foot too far, even.")
|
||
(reverse sentence)
|
||
#+END_SRC
|
||
@end example
|
||
|
||
Noweb insertions honor prefix characters that appear before the Noweb
|
||
syntax reference. This behavior is illustrated in the following
|
||
example. Because the @samp{<<example>>} Noweb reference appears behind the
|
||
SQL comment syntax, each line of the expanded Noweb reference is
|
||
commented. With:
|
||
|
||
@example
|
||
#+NAME: example
|
||
#+BEGIN_SRC text
|
||
this is the
|
||
multi-line body of example
|
||
#+END_SRC
|
||
@end example
|
||
|
||
@noindent
|
||
this code block:
|
||
|
||
@example
|
||
#+BEGIN_SRC sql :noweb yes
|
||
---<<example>>
|
||
#+END_SRC
|
||
@end example
|
||
|
||
@noindent
|
||
expands to:
|
||
|
||
@example
|
||
#+BEGIN_SRC sql :noweb yes
|
||
---this is the
|
||
---multi-line body of example
|
||
#+END_SRC
|
||
@end example
|
||
|
||
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:
|
||
|
||
@example
|
||
#+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
|
||
@end example
|
||
|
||
@noindent
|
||
this code block:
|
||
|
||
@example
|
||
#+begin_src python :noweb yes :results output
|
||
if true:
|
||
<<if-true>>
|
||
else:
|
||
<<if-false>>
|
||
#+end_src
|
||
@end example
|
||
|
||
@noindent
|
||
expands to:
|
||
|
||
@example
|
||
if true:
|
||
print('do things when true')
|
||
else:
|
||
print('do things when false')
|
||
@end example
|
||
|
||
@cindex @samp{noweb-ref}, header argument
|
||
When expanding Noweb style references, Org concatenates code blocks by
|
||
matching the reference name to either the code block name or, if none
|
||
is found, to the @samp{noweb-ref} header argument.
|
||
|
||
For simple concatenation, set this @samp{noweb-ref} header argument at the
|
||
sub-tree or file 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.
|
||
|
||
@example
|
||
#+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
|
||
@end example
|
||
|
||
@cindex @samp{noweb-sep}, header argument
|
||
By default a newline separates each noweb reference concatenation. To
|
||
change this newline separator, edit the @samp{noweb-sep} header argument.
|
||
|
||
Eventually, Org can include the results of a code block rather than
|
||
its body. To that effect, append parentheses, possibly including
|
||
arguments, to the code block name, as shown below.
|
||
|
||
@example
|
||
<<code-block-name(optional arguments)>>
|
||
@end example
|
||
|
||
Note that when using the above approach to a code block's results, the
|
||
code block name set by @samp{NAME} keyword is required; the reference set
|
||
by @samp{noweb-ref} does not work in that case.
|
||
|
||
Here is an example that demonstrates how the exported content changes
|
||
when Noweb style references are used with parentheses versus without.
|
||
With:
|
||
|
||
@example
|
||
#+NAME: some-code
|
||
#+BEGIN_SRC python :var num=0 :results output :exports none
|
||
print(num*10)
|
||
#+END_SRC
|
||
@end example
|
||
|
||
@noindent
|
||
this code block:
|
||
|
||
@example
|
||
#+BEGIN_SRC text :noweb yes
|
||
<<some-code>>
|
||
#+END_SRC
|
||
@end example
|
||
|
||
@noindent
|
||
expands to:
|
||
|
||
@example
|
||
print(num*10)
|
||
@end example
|
||
|
||
Below, a similar Noweb style reference is used, but with parentheses,
|
||
while setting a variable @samp{num} to 10:
|
||
|
||
@example
|
||
#+BEGIN_SRC text :noweb yes
|
||
<<some-code(num=10)>>
|
||
#+END_SRC
|
||
@end example
|
||
|
||
@noindent
|
||
Note that now the expansion contains the results of the code block
|
||
@samp{some-code}, not the code block itself:
|
||
|
||
@example
|
||
100
|
||
@end example
|
||
|
||
@node Library of Babel
|
||
@section Library of Babel
|
||
|
||
@cindex babel, library of
|
||
@cindex source code, library
|
||
@cindex code block, library
|
||
|
||
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 @uref{https://orgmode.org/worg/library-of-babel.html, Worg}. For
|
||
remote code block evaluation syntax, see @ref{Evaluating Code Blocks}.
|
||
|
||
@kindex C-c C-v i
|
||
@findex org-babel-lob-ingest
|
||
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
|
||
@code{org-babel-lob-ingest}, which is bound to @kbd{C-c C-v i}.
|
||
|
||
@node Key bindings and Useful Functions
|
||
@section Key bindings and Useful Functions
|
||
|
||
@cindex code block, key bindings
|
||
|
||
Many common Org mode key sequences are re-bound depending on
|
||
the context.
|
||
|
||
Active key bindings in code blocks:
|
||
|
||
@kindex C-c C-c
|
||
@findex org-babel-execute-src-block
|
||
@kindex C-c C-o
|
||
@findex org-babel-open-src-block-result
|
||
@kindex M-UP
|
||
@findex org-babel-load-in-session
|
||
@kindex M-DOWN
|
||
@findex org-babel-pop-to-session
|
||
@multitable @columnfractions 0.2 0.55
|
||
@headitem Key binding
|
||
@tab Function
|
||
@item @kbd{C-c C-c}
|
||
@tab @code{org-babel-execute-src-block}
|
||
@item @kbd{C-c C-o}
|
||
@tab @code{org-babel-open-src-block-result}
|
||
@item @kbd{M-@key{UP}}
|
||
@tab @code{org-babel-load-in-session}
|
||
@item @kbd{M-@key{DOWN}}
|
||
@tab @code{org-babel-pop-to-session}
|
||
@end multitable
|
||
|
||
Active key bindings in Org mode buffer:
|
||
|
||
@kindex C-c C-v p
|
||
@kindex C-c C-v C-p
|
||
@kindex C-c C-v n
|
||
@kindex C-c C-v C-n
|
||
@kindex C-c C-v e
|
||
@kindex C-c C-v C-e
|
||
@kindex C-c C-v o
|
||
@kindex C-c C-v C-o
|
||
@kindex C-c C-v v
|
||
@kindex C-c C-v C-v
|
||
@kindex C-c C-v u
|
||
@kindex C-c C-v C-u
|
||
@kindex C-c C-v g
|
||
@kindex C-c C-v C-g
|
||
@kindex C-c C-v r
|
||
@kindex C-c C-v C-r
|
||
@kindex C-c C-v b
|
||
@kindex C-c C-v C-b
|
||
@kindex C-c C-v s
|
||
@kindex C-c C-v C-s
|
||
@kindex C-c C-v d
|
||
@kindex C-c C-v C-d
|
||
@kindex C-c C-v t
|
||
@kindex C-c C-v C-t
|
||
@kindex C-c C-v f
|
||
@kindex C-c C-v C-f
|
||
@kindex C-c C-v c
|
||
@kindex C-c C-v C-c
|
||
@kindex C-c C-v j
|
||
@kindex C-c C-v C-j
|
||
@kindex C-c C-v l
|
||
@kindex C-c C-v C-l
|
||
@kindex C-c C-v i
|
||
@kindex C-c C-v C-i
|
||
@kindex C-c C-v I
|
||
@kindex C-c C-v C-I
|
||
@kindex C-c C-v z
|
||
@kindex C-c C-v C-z
|
||
@kindex C-c C-v a
|
||
@kindex C-c C-v C-a
|
||
@kindex C-c C-v h
|
||
@kindex C-c C-v C-h
|
||
@kindex C-c C-v x
|
||
@kindex C-c C-v C-x
|
||
@findex org-babel-previous-src-block
|
||
@findex org-babel-next-src-block
|
||
@findex org-babel-execute-maybe
|
||
@findex org-babel-open-src-block-result
|
||
@findex org-babel-expand-src-block
|
||
@findex org-babel-goto-src-block-head
|
||
@findex org-babel-goto-named-src-block
|
||
@findex org-babel-goto-named-result
|
||
@findex org-babel-execute-buffer
|
||
@findex org-babel-execute-subtree
|
||
@findex org-babel-demarcate-block
|
||
@findex org-babel-tangle
|
||
@findex org-babel-tangle-file
|
||
@findex org-babel-check-src-block
|
||
@findex org-babel-insert-header-arg
|
||
@findex org-babel-load-in-session
|
||
@findex org-babel-lob-ingest
|
||
@findex org-babel-view-src-block-info
|
||
@findex org-babel-switch-to-session-with-code
|
||
@findex org-babel-sha1-hash
|
||
@findex org-babel-describe-bindings
|
||
@findex org-babel-do-key-sequence-in-edit-buffer
|
||
@multitable @columnfractions 0.45 0.55
|
||
@headitem Key binding
|
||
@tab Function
|
||
@item @kbd{C-c C-v p} or @kbd{C-c C-v C-p}
|
||
@tab @code{org-babel-previous-src-block}
|
||
@item @kbd{C-c C-v n} or @kbd{C-c C-v C-n}
|
||
@tab @code{org-babel-next-src-block}
|
||
@item @kbd{C-c C-v e} or @kbd{C-c C-v C-e}
|
||
@tab @code{org-babel-execute-maybe}
|
||
@item @kbd{C-c C-v o} or @kbd{C-c C-v C-o}
|
||
@tab @code{org-babel-open-src-block-result}
|
||
@item @kbd{C-c C-v v} or @kbd{C-c C-v C-v}
|
||
@tab @code{org-babel-expand-src-block}
|
||
@item @kbd{C-c C-v u} or @kbd{C-c C-v C-u}
|
||
@tab @code{org-babel-goto-src-block-head}
|
||
@item @kbd{C-c C-v g} or @kbd{C-c C-v C-g}
|
||
@tab @code{org-babel-goto-named-src-block}
|
||
@item @kbd{C-c C-v r} or @kbd{C-c C-v C-r}
|
||
@tab @code{org-babel-goto-named-result}
|
||
@item @kbd{C-c C-v b} or @kbd{C-c C-v C-b}
|
||
@tab @code{org-babel-execute-buffer}
|
||
@item @kbd{C-c C-v s} or @kbd{C-c C-v C-s}
|
||
@tab @code{org-babel-execute-subtree}
|
||
@item @kbd{C-c C-v d} or @kbd{C-c C-v C-d}
|
||
@tab @code{org-babel-demarcate-block}
|
||
@item @kbd{C-c C-v t} or @kbd{C-c C-v C-t}
|
||
@tab @code{org-babel-tangle}
|
||
@item @kbd{C-c C-v f} or @kbd{C-c C-v C-f}
|
||
@tab @code{org-babel-tangle-file}
|
||
@item @kbd{C-c C-v c} or @kbd{C-c C-v C-c}
|
||
@tab @code{org-babel-check-src-block}
|
||
@item @kbd{C-c C-v j} or @kbd{C-c C-v C-j}
|
||
@tab @code{org-babel-insert-header-arg}
|
||
@item @kbd{C-c C-v l} or @kbd{C-c C-v C-l}
|
||
@tab @code{org-babel-load-in-session}
|
||
@item @kbd{C-c C-v i} or @kbd{C-c C-v C-i}
|
||
@tab @code{org-babel-lob-ingest}
|
||
@item @kbd{C-c C-v I} or @kbd{C-c C-v C-I}
|
||
@tab @code{org-babel-view-src-block-info}
|
||
@item @kbd{C-c C-v z} or @kbd{C-c C-v C-z}
|
||
@tab @code{org-babel-switch-to-session-with-code}
|
||
@item @kbd{C-c C-v a} or @kbd{C-c C-v C-a}
|
||
@tab @code{org-babel-sha1-hash}
|
||
@item @kbd{C-c C-v h} or @kbd{C-c C-v C-h}
|
||
@tab @code{org-babel-describe-bindings}
|
||
@item @kbd{C-c C-v x} or @kbd{C-c C-v C-x}
|
||
@tab @code{org-babel-do-key-sequence-in-edit-buffer}
|
||
@end multitable
|
||
|
||
@node Batch Execution
|
||
@section Batch Execution
|
||
|
||
@cindex code block, batch execution
|
||
@cindex source code, 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
|
||
@code{org-babel-tangle}.
|
||
|
||
@example
|
||
#!/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))))
|
||
" "$@@"
|
||
@end example
|
||
|
||
@node Miscellaneous
|
||
@chapter Miscellaneous
|
||
|
||
@menu
|
||
* Completion:: M-@key{TAB} guesses completions.
|
||
* Structure Templates:: Quick insertion of structural elements.
|
||
* Speed Keys:: Electric commands at the beginning of a headline.
|
||
* Code Evaluation Security:: Org files evaluate in-line code.
|
||
* Customization:: Adapting Org to your taste.
|
||
* In-buffer Settings:: Overview of keywords.
|
||
* The Very Busy @kbd{C-c C-c} Key:: When in doubt, press @kbd{C-c C-c}.
|
||
* Clean View:: Getting rid of leading stars in the outline.
|
||
* TTY Keys:: Using Org on a tty.
|
||
* Interaction:: With other Emacs packages.
|
||
* Org Crypt:: Encrypting Org files.
|
||
@end menu
|
||
|
||
@node Completion
|
||
@section Completion
|
||
|
||
@cindex completion, of @TeX{} symbols
|
||
@cindex completion, of TODO keywords
|
||
@cindex completion, of dictionary words
|
||
@cindex completion, of option keywords
|
||
@cindex completion, of tags
|
||
@cindex completion, of property keys
|
||
@cindex completion, of link abbreviations
|
||
@cindex @TeX{} symbol completion
|
||
@cindex TODO keywords completion
|
||
@cindex dictionary word completion
|
||
@cindex option keyword completion
|
||
@cindex tag completion
|
||
@cindex link abbreviations, completion of
|
||
|
||
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.
|
||
|
||
@table @asis
|
||
@item @kbd{M-@key{TAB}}
|
||
@kindex M-TAB
|
||
|
||
Complete word at point.
|
||
|
||
@itemize
|
||
@item
|
||
At the beginning of a headline, complete TODO keywords.
|
||
|
||
@item
|
||
After @samp{\}, complete @TeX{} symbols supported by the exporter.
|
||
|
||
@item
|
||
After @samp{*}, complete headlines in the current buffer so that
|
||
they can be used in search links like:
|
||
|
||
@example
|
||
[[*find this headline]]
|
||
@end example
|
||
|
||
@item
|
||
After @samp{:} in a headline, complete tags. Org deduces the list
|
||
of tags from the @samp{TAGS} in-buffer option (see @ref{Setting Tags}),
|
||
the variable @code{org-tag-alist}, or from all tags used in the
|
||
current buffer.
|
||
|
||
@item
|
||
After @samp{:} and not in a headline, complete property keys. The
|
||
list of keys is constructed dynamically from all keys used in
|
||
the current buffer.
|
||
|
||
@item
|
||
After @samp{[}, complete link abbreviations (see @ref{Link Abbreviations}).
|
||
|
||
@item
|
||
After @samp{#+}, complete the special keywords like @samp{TYP_TODO} or
|
||
file-specific @samp{OPTIONS}. After option keyword is complete,
|
||
pressing @kbd{M-@key{TAB}} again inserts example settings for
|
||
this keyword.
|
||
|
||
@item
|
||
After @samp{STARTUP} keyword, complete startup items.
|
||
|
||
@item
|
||
When point is anywhere else, complete dictionary words using
|
||
Ispell.
|
||
@end itemize
|
||
@end table
|
||
|
||
@node Structure Templates
|
||
@section Structure Templates
|
||
|
||
@cindex template insertion
|
||
@cindex insertion, of templates
|
||
|
||
With just a few keystrokes, it is possible to insert empty structural
|
||
blocks, such as @samp{#+BEGIN_SRC} @dots{} @samp{#+END_SRC}, or to wrap existing
|
||
text in such a block.
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-,} (@code{org-insert-structure-template})
|
||
@findex org-insert-structure-template
|
||
@kindex C-c C-,
|
||
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
|
||
@kbd{@key{TAB}}, @kbd{@key{RET}}, or @kbd{@key{SPC}}, the user is
|
||
prompted to enter a block type.
|
||
@end table
|
||
|
||
@vindex org-structure-template-alist
|
||
Available structure types are defined in
|
||
@code{org-structure-template-alist}, see the docstring for adding or
|
||
changing values.
|
||
|
||
@cindex Tempo
|
||
@cindex template expansion
|
||
@cindex insertion, of templates
|
||
@vindex org-tempo-keywords-alist
|
||
Org Tempo expands snippets to structures defined in
|
||
@code{org-structure-template-alist} and @code{org-tempo-keywords-alist}. For
|
||
example, @kbd{< s @key{TAB}} creates a code block. Enable it by
|
||
customizing @code{org-modules} or add @code{(require 'org-tempo)} to your Emacs
|
||
init file@footnote{For more information, please refer to the commentary section
|
||
in @samp{org-tempo.el}.}.
|
||
|
||
|
||
@multitable @columnfractions 0.1 0.9
|
||
@item @kbd{a}
|
||
@tab @samp{#+BEGIN_EXPORT ascii} @dots{} @samp{#+END_EXPORT}
|
||
@item @kbd{c}
|
||
@tab @samp{#+BEGIN_CENTER} @dots{} @samp{#+END_CENTER}
|
||
@item @kbd{C}
|
||
@tab @samp{#+BEGIN_COMMENT} @dots{} @samp{#+END_COMMENT}
|
||
@item @kbd{e}
|
||
@tab @samp{#+BEGIN_EXAMPLE} @dots{} @samp{#+END_EXAMPLE}
|
||
@item @kbd{h}
|
||
@tab @samp{#+BEGIN_EXPORT html} @dots{} @samp{#+END_EXPORT}
|
||
@item @kbd{l}
|
||
@tab @samp{#+BEGIN_EXPORT latex} @dots{} @samp{#+END_EXPORT}
|
||
@item @kbd{q}
|
||
@tab @samp{#+BEGIN_QUOTE} @dots{} @samp{#+END_QUOTE}
|
||
@item @kbd{s}
|
||
@tab @samp{#+BEGIN_SRC} @dots{} @samp{#+END_SRC}
|
||
@item @kbd{v}
|
||
@tab @samp{#+BEGIN_VERSE} @dots{} @samp{#+END_VERSE}
|
||
@end multitable
|
||
|
||
@node Speed Keys
|
||
@section Speed Keys
|
||
|
||
@cindex speed keys
|
||
|
||
Single keystrokes can execute custom commands in an Org file when the
|
||
cursor 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.
|
||
|
||
@vindex org-use-speed-commands
|
||
By default, Org has Speed Keys disabled. To activate Speed Keys, set
|
||
the variable @code{org-use-speed-commands} to a non-@code{nil} value. To
|
||
trigger a Speed Key, the cursor must be at the beginning of an Org
|
||
headline, before any of the stars.
|
||
|
||
@vindex org-speed-commands-user
|
||
@findex org-speed-command-help
|
||
Org comes with a pre-defined list of Speed Keys. To add or modify
|
||
Speed Keys, customize the variable, @code{org-speed-commands-user}. For
|
||
more details, see the variable's docstring. With Speed Keys
|
||
activated, @kbd{M-x org-speed-command-help}, or @kbd{?} when
|
||
cursor is at the beginning of an Org headline, shows currently active
|
||
Speed Keys, including the user-defined ones.
|
||
|
||
@node Code Evaluation Security
|
||
@section Code Evaluation and Security Issues
|
||
|
||
Unlike plain text, running code comes with risk. Each @samp{src} 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:
|
||
|
||
@table @asis
|
||
@item @emph{Source code blocks}
|
||
Org evaluates @samp{src} code blocks in an Org file during export.
|
||
Org also evaluates a @samp{src} code block with the @kbd{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.
|
||
|
||
@defopt org-confirm-babel-evaluate
|
||
When @code{t}, Org prompts the user for confirmation before executing
|
||
each code block. When @code{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 @code{t} or @code{nil},
|
||
which determines if the user is prompted. Each source code
|
||
language can be handled separately through this function
|
||
argument.
|
||
@end defopt
|
||
|
||
For example, here is how to execute ditaa code blocks without
|
||
prompting:
|
||
|
||
@lisp
|
||
(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)
|
||
@end lisp
|
||
|
||
@item @emph{Following @samp{shell} and @samp{elisp} links}
|
||
Org has two link types that can directly evaluate code (see
|
||
@ref{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:
|
||
|
||
@defopt org-confirm-shell-link-function
|
||
Function that prompts the user before executing a shell link.
|
||
@end defopt
|
||
|
||
@defopt org-confirm-elisp-link-function
|
||
Function that prompts the user before executing an Emacs Lisp link.
|
||
@end defopt
|
||
|
||
@item @emph{Formulas in tables}
|
||
Formulas in tables (see @ref{The spreadsheet}) are code that is
|
||
evaluated either by the Calc interpreter, or by the Emacs Lisp
|
||
interpreter.
|
||
@end table
|
||
|
||
@node Customization
|
||
@section Customization
|
||
|
||
@cindex customization
|
||
@cindex options, for customization
|
||
@cindex variables, for customization
|
||
|
||
Org has more than 500 variables for customization. They can be
|
||
accessed through the usual @kbd{M-x org-customize} command. Or
|
||
through the Org menu: Org @arrow{} Customization @arrow{} Browse Org Group.
|
||
|
||
Org also has per-file settings for some variables (see @ref{In-buffer Settings}).
|
||
|
||
@node In-buffer Settings
|
||
@section Summary of In-Buffer Settings
|
||
|
||
@cindex in-buffer settings
|
||
@cindex special keywords
|
||
|
||
In-buffer settings start with @samp{#+}, 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.
|
||
|
||
@cindex refresh set-up
|
||
@kbd{C-c C-c} activates any changes to the in-buffer settings.
|
||
Closing and reopening the Org file in Emacs also activates the
|
||
changes.
|
||
|
||
@table @asis
|
||
@item @samp{#+ARCHIVE: %s_done}
|
||
@cindex @samp{ARCHIVE}, keyword
|
||
@vindex org-archive-location
|
||
Sets the archive location of the agenda file. The corresponding
|
||
variable is @code{org-archive-location}.
|
||
|
||
@item @samp{#+CATEGORY}
|
||
@cindex @samp{CATEGORY}, keyword
|
||
Sets the category of the agenda file, which applies to the entire
|
||
document.
|
||
|
||
@item @samp{#+COLUMNS: %25ITEM ...}
|
||
@cindex @samp{COLUMNS}, property
|
||
Set the default format for columns view. This format applies
|
||
when columns view is invoked in locations where no @samp{COLUMNS}
|
||
property applies.
|
||
|
||
@item @samp{#+CONSTANTS: name1=value1 ...}
|
||
@cindex @samp{CONSTANTS}, keyword
|
||
@vindex org-table-formula-constants
|
||
@vindex org-table-formula
|
||
Set file-local values for constants that table formulas can use.
|
||
This line sets the local variable
|
||
@code{org-table-formula-constants-local}. The global version of this
|
||
variable is @code{org-table-formula-constants}.
|
||
|
||
@item @samp{#+FILETAGS: :tag1:tag2:tag3:}
|
||
@cindex @samp{FILETAGS}, keyword
|
||
Set tags that all entries in the file inherit from, including the
|
||
top-level entries.
|
||
|
||
@item @samp{#+LINK: linkword replace}
|
||
@cindex @samp{LINK}, keyword
|
||
@vindex org-link-abbrev-alist
|
||
Each line specifies one abbreviation for one link. Use multiple
|
||
@samp{LINK} keywords for more, see @ref{Link Abbreviations}. The
|
||
corresponding variable is @code{org-link-abbrev-alist}.
|
||
|
||
@item @samp{#+PRIORITIES: highest lowest default}
|
||
@cindex @samp{PRIORITIES}, keyword
|
||
@vindex org-highest-priority
|
||
@vindex org-lowest-priority
|
||
@vindex org-default-priority
|
||
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.
|
||
|
||
@item @samp{#+PROPERTY: Property_Name Value}
|
||
@cindex @samp{PROPERTY}, keyword
|
||
This line sets a default inheritance value for entries in the
|
||
current buffer, most useful for specifying the allowed values of
|
||
a property.
|
||
|
||
@item @samp{#+SETUPFILE: file}
|
||
@cindex @samp{SETUPFILE}, keyword
|
||
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. @kbd{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 @kbd{C-c '} while the cursor is
|
||
on the line with the file name.
|
||
|
||
@item @samp{#+STARTUP:}
|
||
@cindex @samp{STARTUP}, keyword
|
||
Startup options Org uses when first visiting a file.
|
||
|
||
@vindex org-startup-folded
|
||
The first set of options deals with the initial visibility of the
|
||
outline tree. The corresponding variable for global default
|
||
settings is @code{org-startup-folded} with a default value of @code{t},
|
||
which is the same as @code{overview}.
|
||
|
||
@table @asis
|
||
@item @samp{overview}
|
||
Top-level headlines only.
|
||
|
||
@item @samp{content}
|
||
All headlines.
|
||
|
||
@item @samp{showall}
|
||
No folding on any entry.
|
||
|
||
@item @samp{showeverything}
|
||
Show even drawer contents.
|
||
@end table
|
||
|
||
@vindex org-startup-indented
|
||
Dynamic virtual indentation is controlled by the variable
|
||
@code{org-startup-indented}.@footnote{Note that @code{org-indent-mode} also sets the @code{wrap-prefix}
|
||
property, such that @code{visual-line-mode} (or purely setting @code{word-wrap})
|
||
wraps long lines (including headlines) correctly indented.}
|
||
|
||
@table @asis
|
||
@item @samp{indent}
|
||
Start with @code{org-indent-mode} turned on.
|
||
|
||
@item @samp{noindent}
|
||
Start with @code{org-indent-mode} turned off.
|
||
@end table
|
||
|
||
@vindex org-startup-align-all-tables
|
||
Aligns tables consistently upon visiting a file. The corresponding
|
||
variable is @code{org-startup-align-all-tables} with @code{nil} as default
|
||
value.
|
||
|
||
@table @asis
|
||
@item @samp{align}
|
||
Align all tables.
|
||
|
||
@item @samp{noalign}
|
||
Do not align tables on startup.
|
||
@end table
|
||
|
||
@vindex org-startup-shrink-all-tables
|
||
Shrink table columns with a width cookie. The corresponding
|
||
variable is @code{org-startup-shrink-all-tables} with @code{nil} as default
|
||
value.
|
||
|
||
@vindex org-startup-with-inline-images
|
||
When visiting a file, inline images can be automatically displayed.
|
||
The corresponding variable is @code{org-startup-with-inline-images},
|
||
with a default value @code{nil} to avoid delays when visiting a file.
|
||
|
||
@table @asis
|
||
@item @samp{inlineimages}
|
||
Show inline images.
|
||
|
||
@item @samp{noinlineimages}
|
||
Do not show inline images on startup.
|
||
@end table
|
||
|
||
@vindex org-log-done
|
||
@vindex org-log-note-clock-out
|
||
@vindex org-log-repeat
|
||
Logging the closing and reopening of TODO items and clock
|
||
intervals can be configured using these options (see variables
|
||
@code{org-log-done}, @code{org-log-note-clock-out}, and @code{org-log-repeat}).
|
||
|
||
@table @asis
|
||
@item @samp{logdone}
|
||
Record a timestamp when an item is marked DONE.
|
||
|
||
@item @samp{lognotedone}
|
||
Record timestamp and a note when DONE.
|
||
|
||
@item @samp{nologdone}
|
||
Do not record when items are marked DONE.
|
||
|
||
@item @samp{logrepeat}
|
||
Record a time when reinstating a repeating item.
|
||
|
||
@item @samp{lognoterepeat}
|
||
Record a note when reinstating a repeating item.
|
||
|
||
@item @samp{nologrepeat}
|
||
Do not record when reinstating repeating item.
|
||
|
||
@item @samp{lognoteclock-out}
|
||
Record a note when clocking out.
|
||
|
||
@item @samp{nolognoteclock-out}
|
||
Do not record a note when clocking out.
|
||
|
||
@item @samp{logreschedule}
|
||
Record a timestamp when scheduling time changes.
|
||
|
||
@item @samp{lognotereschedule}
|
||
Record a note when scheduling time changes.
|
||
|
||
@item @samp{nologreschedule}
|
||
Do not record when a scheduling date changes.
|
||
|
||
@item @samp{logredeadline}
|
||
Record a timestamp when deadline changes.
|
||
|
||
@item @samp{lognoteredeadline}
|
||
Record a note when deadline changes.
|
||
|
||
@item @samp{nologredeadline}
|
||
Do not record when a deadline date changes.
|
||
|
||
@item @samp{logrefile}
|
||
Record a timestamp when refiling.
|
||
|
||
@item @samp{lognoterefile}
|
||
Record a note when refiling.
|
||
|
||
@item @samp{nologrefile}
|
||
Do not record when refiling.
|
||
@end table
|
||
|
||
@vindex org-hide-leading-stars
|
||
@vindex org-odd-levels-only
|
||
Here are the options for hiding leading stars in outline headings,
|
||
and for indenting outlines. The corresponding variables are
|
||
@code{org-hide-leading-stars} and @code{org-odd-levels-only}, both with
|
||
a default setting @code{nil} (meaning @samp{showstars} and @samp{oddeven}).
|
||
|
||
@table @asis
|
||
@item @samp{hidestars}
|
||
Make all but one of the stars starting a headline invisible.
|
||
|
||
@item @samp{showstars}
|
||
Show all stars starting a headline.
|
||
|
||
@item @samp{indent}
|
||
Virtual indentation according to outline level.
|
||
|
||
@item @samp{noindent}
|
||
No virtual indentation according to outline level.
|
||
|
||
@item @samp{odd}
|
||
Allow only odd outline levels (1, 3, @dots{}).
|
||
|
||
@item @samp{oddeven}
|
||
Allow all outline levels.
|
||
@end table
|
||
|
||
@vindex org-put-time-stamp-overlays
|
||
@vindex org-time-stamp-overlay-formats
|
||
To turn on custom format overlays over timestamps (variables
|
||
@code{org-put-time-stamp-overlays} and @code{org-time-stamp-overlay-formats}),
|
||
use:
|
||
|
||
@table @asis
|
||
@item @samp{customtime}
|
||
Overlay custom time format.
|
||
@end table
|
||
|
||
@vindex constants-unit-system
|
||
The following options influence the table spreadsheet (variable
|
||
@code{constants-unit-system}).
|
||
|
||
@table @asis
|
||
@item @samp{constcgs}
|
||
@samp{constants.el} should use the c-g-s unit system.
|
||
|
||
@item @samp{constSI}
|
||
@samp{constants.el} should use the SI unit system.
|
||
@end table
|
||
|
||
@vindex org-footnote-define-inline
|
||
@vindex org-footnote-auto-label
|
||
@vindex org-footnote-auto-adjust
|
||
To influence footnote settings, use the following keywords. The
|
||
corresponding variables are @code{org-footnote-define-inline},
|
||
@code{org-footnote-auto-label}, and @code{org-footnote-auto-adjust}.
|
||
|
||
@table @asis
|
||
@item @samp{fninline}
|
||
Define footnotes inline.
|
||
|
||
@item @samp{fnnoinline}
|
||
Define footnotes in separate section.
|
||
|
||
@item @samp{fnlocal}
|
||
Define footnotes near first reference, but not inline.
|
||
|
||
@item @samp{fnprompt}
|
||
Prompt for footnote labels.
|
||
|
||
@item @samp{fnauto}
|
||
Create @samp{[fn:1]}-like labels automatically (default).
|
||
|
||
@item @samp{fnconfirm}
|
||
Offer automatic label for editing or confirmation.
|
||
|
||
@item @samp{fnadjust}
|
||
Automatically renumber and sort footnotes.
|
||
|
||
@item @samp{nofnadjust}
|
||
Do not renumber and sort automatically.
|
||
@end table
|
||
|
||
@vindex org-hide-block-startup
|
||
To hide blocks on startup, use these keywords. The corresponding
|
||
variable is @code{org-hide-block-startup}.
|
||
|
||
@table @asis
|
||
@item @samp{hideblocks}
|
||
Hide all begin/end blocks on startup.
|
||
|
||
@item @samp{nohideblocks}
|
||
Do not hide blocks on startup.
|
||
@end table
|
||
|
||
@vindex org-pretty-entities
|
||
The display of entities as UTF-8 characters is governed by the
|
||
variable @code{org-pretty-entities} and the keywords
|
||
|
||
@table @asis
|
||
@item @samp{entitiespretty}
|
||
Show entities as UTF-8 characters where possible.
|
||
|
||
@item @samp{entitiesplain}
|
||
Leave entities plain.
|
||
@end table
|
||
|
||
@item @samp{#+TAGS: TAG1(c1) TAG2(c2)}
|
||
@cindex @samp{TAGS}, keyword
|
||
@vindex org-tag-alist
|
||
These lines (several such lines are allowed) specify the valid
|
||
tags in this file, and (potentially) the corresponding @emph{fast tag
|
||
selection} keys. The corresponding variable is @code{org-tag-alist}.
|
||
|
||
@item @samp{#+TODO:}
|
||
@itemx @samp{#+SEQ_TODO:}
|
||
@itemx @samp{#+TYP_TODO:}
|
||
@cindex @samp{SEQ_TODO}, keyword
|
||
@cindex @samp{TODO}, keyword
|
||
@cindex @samp{TYP_TODO}, keyword
|
||
@vindex org-todo-keywords
|
||
These lines set the TODO keywords and their interpretation in the
|
||
current file. The corresponding variable is @code{org-todo-keywords}.
|
||
@end table
|
||
|
||
@node The Very Busy @kbd{C-c C-c} Key
|
||
@section The Very Busy @kbd{C-c C-c} Key
|
||
|
||
@kindex C-c C-c
|
||
@cindex @kbd{C-c C-c}, overview
|
||
|
||
The @kbd{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.
|
||
|
||
@itemize
|
||
@item
|
||
If any highlights shown in the buffer from the creation of a sparse
|
||
tree, or from clock display, remove such highlights.
|
||
|
||
@item
|
||
If the cursor is in one of the special @samp{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 @samp{SETUPFILE}.
|
||
|
||
@item
|
||
If the cursor is inside a table, realign the table. The table
|
||
realigns even if automatic table editor is turned off.
|
||
|
||
@item
|
||
If the cursor is on a @samp{TBLFM} keyword, re-apply the formulas to the
|
||
entire table.
|
||
|
||
@item
|
||
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.
|
||
|
||
@item
|
||
If the cursor is on a @samp{<<<target>>>}, update radio targets and
|
||
corresponding links in this buffer.
|
||
|
||
@item
|
||
If the cursor is on a property line or at the start or end of
|
||
a property drawer, offer property commands.
|
||
|
||
@item
|
||
If the cursor is at a footnote reference, go to the corresponding
|
||
definition, and @emph{vice versa}.
|
||
|
||
@item
|
||
If the cursor is on a statistics cookie, update it.
|
||
|
||
@item
|
||
If the cursor is in a plain list item with a checkbox, toggle the
|
||
status of the checkbox.
|
||
|
||
@item
|
||
If the cursor is on a numbered item in a plain list, renumber the
|
||
ordered list.
|
||
|
||
@item
|
||
If the cursor is on the @samp{#+BEGIN} line of a dynamic block, the block
|
||
is updated.
|
||
|
||
@item
|
||
If the cursor is at a timestamp, fix the day name in the timestamp.
|
||
@end itemize
|
||
|
||
@node Clean View
|
||
@section A Cleaner Outline View
|
||
|
||
@cindex hiding leading stars
|
||
@cindex dynamic indentation
|
||
@cindex odd-levels-only outlines
|
||
@cindex clean outline view
|
||
|
||
Org's default outline with stars and no indents can become too
|
||
cluttered for short documents. For @emph{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
|
||
uses only one star and indents text to line with the heading:
|
||
|
||
@example
|
||
* 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
|
||
@end example
|
||
|
||
@noindent
|
||
@cindex Indent mode
|
||
@findex org-indent-mode
|
||
To turn this mode on, use the minor mode, @code{org-indent-mode}. Text
|
||
lines that are not headlines are prefixed with spaces to vertically
|
||
align with the headline text@footnote{The @code{org-indent-mode} also sets the @code{wrap-prefix} correctly
|
||
for indenting and wrapping long lines of headlines or text. This
|
||
minor mode handles @code{visual-line-mode} and directly applied settings
|
||
through @code{word-wrap}.}.
|
||
|
||
@vindex org-indent-indentation-per-level
|
||
To make more horizontal space, the headlines are shifted by two stars.
|
||
This can be configured by the @code{org-indent-indentation-per-level}
|
||
variable. Only one star on each headline is visible, the rest are
|
||
masked with the same font color as the background.
|
||
|
||
Note that turning on @code{org-indent-mode} sets @code{org-hide-leading-stars}
|
||
to @code{t} and @code{org-adapt-indentation} to @code{nil}.
|
||
|
||
@vindex org-startup-indented
|
||
To globally turn on @code{org-indent-mode} for all files, customize the
|
||
variable @code{org-startup-indented}.
|
||
|
||
To turn on indenting for individual files, use @samp{STARTUP} keyword as
|
||
follows:
|
||
|
||
@example
|
||
#+STARTUP: indent
|
||
@end example
|
||
|
||
Indent on startup makes Org use hard spaces to align text with
|
||
headings as shown in examples below.
|
||
|
||
@table @asis
|
||
@item @emph{Indentation of text below headlines}
|
||
Indent text to align with the headline.
|
||
|
||
@example
|
||
*** Third level
|
||
more text, now indented
|
||
@end example
|
||
|
||
@vindex org-adapt-indentation
|
||
Org supports this with paragraph filling, line wrapping, and
|
||
structure editing, preserving or adapting the indentation as
|
||
appropriate@footnote{Also see the variable @code{org-adapt-indentation}.}.
|
||
|
||
@item @emph{Hiding leading stars}
|
||
@vindex org-hide-leading-stars
|
||
Org can make leading stars invisible. For global preference,
|
||
configure the variable @code{org-hide-leading-stars}. For per-file
|
||
preference, use these file @samp{STARTUP} options:
|
||
|
||
@example
|
||
#+STARTUP: hidestars
|
||
#+STARTUP: showstars
|
||
@end example
|
||
|
||
With stars hidden, the tree is shown as:
|
||
|
||
@example
|
||
* Top level headline
|
||
* Second level
|
||
* Third level
|
||
...
|
||
@end example
|
||
|
||
@noindent
|
||
@vindex org-hide, face
|
||
Because Org makes the font color the same as the background color
|
||
to hide to stars, sometimes @code{org-hide} face may need tweaking to
|
||
get the effect right. For some black and white combinations,
|
||
@code{grey90} on a white background might mask the stars better.
|
||
|
||
@item @emph{Odd levels}
|
||
@vindex org-odd-levels-only
|
||
Using stars for only odd levels, 1, 3, 5, @dots{}, can also clean up
|
||
the clutter. This removes two stars from each level@footnote{Because @samp{LEVEL=2} has 3 stars, @samp{LEVEL=3} has 4 stars, and so
|
||
on.}.
|
||
For Org to properly handle this cleaner structure during edits
|
||
and exports, configure the variable @code{org-odd-levels-only}. To
|
||
set this per-file, use either one of the following lines:
|
||
|
||
@example
|
||
#+STARTUP: odd
|
||
#+STARTUP: oddeven
|
||
@end example
|
||
|
||
To switch between single and double stars layouts, use @kbd{M-x org-convert-to-odd-levels} and @kbd{M-x org-convert-to-oddeven-levels}.
|
||
@end table
|
||
|
||
@node TTY Keys
|
||
@section Using Org on a TTY
|
||
|
||
@cindex tty key bindings
|
||
|
||
Org provides alternative key bindings for TTY and modern mobile
|
||
devices that cannot handle cursor keys and complex modifier key
|
||
chords. 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 @kbd{S-<cursor>} for
|
||
editing timestamp might be better with @kbd{C-c .} chord.
|
||
|
||
@multitable @columnfractions 0.2 0.28 0.15 0.21
|
||
@headitem Default
|
||
@tab Alternative 1
|
||
@tab Speed key
|
||
@tab Alternative 2
|
||
@item @kbd{S-@key{TAB}}
|
||
@tab @kbd{C-u @key{TAB}}
|
||
@tab @kbd{C}
|
||
@tab
|
||
@item @kbd{M-@key{LEFT}}
|
||
@tab @kbd{C-c C-x l}
|
||
@tab @kbd{l}
|
||
@tab @kbd{Esc @key{LEFT}}
|
||
@item @kbd{M-S-@key{LEFT}}
|
||
@tab @kbd{C-c C-x L}
|
||
@tab @kbd{L}
|
||
@tab
|
||
@item @kbd{M-@key{RIGHT}}
|
||
@tab @kbd{C-c C-x r}
|
||
@tab @kbd{r}
|
||
@tab @kbd{Esc @key{RIGHT}}
|
||
@item @kbd{M-S-@key{RIGHT}}
|
||
@tab @kbd{C-c C-x R}
|
||
@tab @kbd{R}
|
||
@tab
|
||
@item @kbd{M-@key{UP}}
|
||
@tab @kbd{C-c C-x u}
|
||
@tab
|
||
@tab @kbd{Esc @key{UP}}
|
||
@item @kbd{M-S-@key{UP}}
|
||
@tab @kbd{C-c C-x U}
|
||
@tab @kbd{U}
|
||
@tab
|
||
@item @kbd{M-@key{DOWN}}
|
||
@tab @kbd{C-c C-x d}
|
||
@tab
|
||
@tab @kbd{Esc @key{DOWN}}
|
||
@item @kbd{M-S-@key{DOWN}}
|
||
@tab @kbd{C-c C-x D}
|
||
@tab @kbd{D}
|
||
@tab
|
||
@item @kbd{S-@key{RET}}
|
||
@tab @kbd{C-c C-x c}
|
||
@tab
|
||
@tab
|
||
@item @kbd{M-@key{RET}}
|
||
@tab @kbd{C-c C-x m}
|
||
@tab
|
||
@tab @kbd{Esc @key{RET}}
|
||
@item @kbd{M-S-@key{RET}}
|
||
@tab @kbd{C-c C-x M}
|
||
@tab
|
||
@tab
|
||
@item @kbd{S-@key{LEFT}}
|
||
@tab @kbd{C-c @key{LEFT}}
|
||
@tab
|
||
@tab
|
||
@item @kbd{S-@key{RIGHT}}
|
||
@tab @kbd{C-c @key{RIGHT}}
|
||
@tab
|
||
@tab
|
||
@item @kbd{S-@key{UP}}
|
||
@tab @kbd{C-c @key{UP}}
|
||
@tab
|
||
@tab
|
||
@item @kbd{S-@key{DOWN}}
|
||
@tab @kbd{C-c @key{DOWN}}
|
||
@tab
|
||
@tab
|
||
@item @kbd{C-S-@key{LEFT}}
|
||
@tab @kbd{C-c C-x @key{LEFT}}
|
||
@tab
|
||
@tab
|
||
@item @kbd{C-S-@key{RIGHT}}
|
||
@tab @kbd{C-c C-x @key{RIGHT}}
|
||
@tab
|
||
@tab
|
||
@end multitable
|
||
|
||
@node Interaction
|
||
@section Interaction with Other Packages
|
||
|
||
@cindex packages, interaction with other
|
||
|
||
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.
|
||
@end menu
|
||
|
||
@node Cooperation
|
||
@subsection Packages that Org cooperates with
|
||
|
||
@table @asis
|
||
@item @samp{calc.el} by Dave Gillespie
|
||
@cindex @file{calc.el}
|
||
|
||
Org uses the Calc package for implementing spreadsheet
|
||
functionality in its tables (see @ref{The spreadsheet}). Org also
|
||
uses Calc for embedded calculations. See @ref{Embedded Mode,GNU Emacs Calc Manual,,calc,}.
|
||
|
||
@item @samp{constants.el} by Carsten Dominik
|
||
@cindex @file{constants.el}
|
||
@vindex org-table-formula-constants
|
||
|
||
Org can use names for constants in formulas in tables. Org can
|
||
also use calculation suffixes for units, such as @samp{M} for @samp{Mega}.
|
||
For a standard collection of such constants, install the
|
||
@samp{constants} package. Install version 2.0 of this package,
|
||
available at @uref{http://www.astro.uva.nl/~dominik/Tools}. Org checks
|
||
if the function @code{constants-get} has been autoloaded.
|
||
Installation instructions are in the file @samp{constants.el}.
|
||
|
||
@item @samp{cdlatex.el} by Carsten Dominik
|
||
@cindex @file{cdlatex.el}
|
||
|
||
Org mode can make use of the CD@LaTeX{} package to efficiently enter
|
||
@LaTeX{} fragments into Org files. See @ref{CD@LaTeX{} mode}.
|
||
|
||
@item @samp{imenu.el} by Ake Stenhoff and Lars Lindberg
|
||
@cindex @file{imenu.el}
|
||
|
||
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:
|
||
|
||
@lisp
|
||
(add-hook 'org-mode-hook
|
||
(lambda () (imenu-add-to-menubar "Imenu")))
|
||
@end lisp
|
||
|
||
@vindex org-imenu-depth
|
||
By default the index is two levels deep---you can modify the
|
||
depth using the option @code{org-imenu-depth}.
|
||
|
||
@item @samp{speedbar.el} by Eric M. Ludlam
|
||
@cindex @file{speedbar.el}
|
||
|
||
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
|
||
@kbd{<} in the Speedbar frame tweaks the agenda commands to
|
||
that file or to a subtree.
|
||
|
||
@item @samp{table.el} by Takaaki Ota
|
||
@cindex table editor, @file{table.el}
|
||
@cindex @file{table.el}
|
||
|
||
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. @kbd{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.
|
||
|
||
@table @asis
|
||
@item @kbd{C-c '} (@code{org-edit-special})
|
||
@kindex C-c '
|
||
@findex org-edit-special
|
||
Edit a @samp{table.el} table. Works when the cursor is in
|
||
a @samp{table.el} table.
|
||
|
||
@item @kbd{C-c ~} (@code{org-table-create-with-table.el})
|
||
@kindex C-c ~
|
||
@findex org-table-create-with-table.el
|
||
Insert a @samp{table.el} table. If there is already a table at
|
||
point, this command converts it between the @samp{table.el}
|
||
format and the Org mode format. See the documentation
|
||
string of the command @code{org-convert-table} for the
|
||
restrictions under which this is possible.
|
||
@end table
|
||
@end table
|
||
|
||
@node Conflicts
|
||
@subsection Packages that conflict with Org mode
|
||
|
||
@cindex shift-selection-mode
|
||
@vindex org-support-shift-select
|
||
In Emacs, @code{shift-selection-mode} combines cursor motions with shift
|
||
key to enlarge regions. Emacs sets this mode by default. This
|
||
conflicts with Org's use of @kbd{S-<cursor>} commands to change
|
||
timestamps, TODO keywords, priorities, and item bullet types, etc.
|
||
Since @kbd{S-<cursor>} commands outside of specific contexts do
|
||
not do anything, Org offers the variable @code{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
|
||
the cursor moves across a special context.
|
||
|
||
@table @asis
|
||
@item @samp{cua.el} by Kim. F. Storm
|
||
@cindex @file{cua.el}
|
||
@vindex org-replace-disputed-keys
|
||
Org key bindings conflict with @kbd{S-<cursor>} keys used by
|
||
CUA mode. For Org to relinquish these bindings to CUA mode,
|
||
configure the variable @code{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.
|
||
|
||
@multitable @columnfractions 0.4 0.4
|
||
@item @kbd{S-@key{UP}} @result{} @kbd{M-p}
|
||
@tab @kbd{S-@key{DOWN}} @result{} @kbd{M-n}
|
||
@item @kbd{S-@key{LEFT}} @result{} @kbd{M--}
|
||
@tab @kbd{S-@key{RIGHT}} @result{} @kbd{M-+}
|
||
@item @kbd{C-S-@key{LEFT}} @result{} @kbd{M-S--}
|
||
@tab @kbd{C-S-@key{RIGHT}} @result{} @kbd{M-S-+}
|
||
@end multitable
|
||
|
||
@vindex org-disputed-keys
|
||
Yes, these are unfortunately more difficult to remember. If you
|
||
want to have other replacement keys, look at the variable
|
||
@code{org-disputed-keys}.
|
||
|
||
@item @samp{ecomplete.el} by Lars Magne Ingebrigtsen
|
||
@cindex @file{ecomplete.el}
|
||
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 @emph{not}
|
||
follow the advice to automagically turn on Orgtbl mode in message
|
||
buffers (see @ref{Orgtbl Mode}), but instead---after
|
||
filling in the message headers---turn on Orgtbl mode manually
|
||
when needed in the messages body.
|
||
|
||
@item @samp{filladapt.el} by Kyle Jones
|
||
@cindex @file{filladapt.el}
|
||
Org mode tries to do the right thing when filling paragraphs,
|
||
list items and other elements. Many users reported problems
|
||
using both @samp{filladapt.el} and Org mode, so a safe thing to do is
|
||
to disable filladapt like this:
|
||
|
||
@lisp
|
||
(add-hook 'org-mode-hook 'turn-off-filladapt-mode)
|
||
@end lisp
|
||
|
||
@item @samp{viper.el} by Michael Kifer
|
||
@cindex @file{viper.el}
|
||
@kindex C-c /
|
||
|
||
Viper uses @kbd{C-c /} and therefore makes this key not
|
||
access the corresponding Org mode command @code{org-sparse-tree}. You
|
||
need to find another key for this command, or override the key in
|
||
@code{viper-vi-global-user-map} with
|
||
|
||
@lisp
|
||
(define-key viper-vi-global-user-map "C-c /" 'org-sparse-tree)
|
||
@end lisp
|
||
|
||
@item @samp{windmove.el} by Hovav Shacham
|
||
@cindex @file{windmove.el}
|
||
|
||
This package also uses the @kbd{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 @kbd{S-<cursor>}, add this to your configuration:
|
||
|
||
@lisp
|
||
;; 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)
|
||
@end lisp
|
||
|
||
@item @samp{yasnippet.el}
|
||
@cindex @file{yasnippet.el}
|
||
The way Org mode binds the @kbd{@key{TAB}} key (binding to @code{[tab]}
|
||
instead of @code{"\t"}) overrules YASnippet's access to this key. The
|
||
following code fixed this problem:
|
||
|
||
@lisp
|
||
(add-hook 'org-mode-hook
|
||
(lambda ()
|
||
(setq-local yas/trigger-key [tab])
|
||
(define-key yas/keymap [tab] 'yas/next-field-or-maybe-expand)))
|
||
@end lisp
|
||
|
||
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:
|
||
|
||
@lisp
|
||
(defun yas/org-very-safe-expand ()
|
||
(let ((yas/fallback-behavior 'return-nil)) (yas/expand)))
|
||
@end lisp
|
||
|
||
Then, tell Org mode to use that function:
|
||
|
||
@lisp
|
||
(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)))
|
||
@end lisp
|
||
@end table
|
||
|
||
@node Org Crypt
|
||
@section Org Crypt
|
||
|
||
Org Crypt encrypts the text of an entry, but not the headline, or
|
||
properties. Behind the scene, it uses the Emacs EasyPG library to
|
||
encrypt and decrypt files.
|
||
|
||
@vindex org-crypt-tag-matcher
|
||
Any text below a headline that has a @samp{crypt} tag is automatically
|
||
encrypted when the file is saved. To use a different tag, customize
|
||
the @code{org-crypt-tag-matcher} setting.
|
||
|
||
Here is a suggestion for Org Crypt settings in Emacs init file:
|
||
|
||
@lisp
|
||
(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; -*-
|
||
@end lisp
|
||
|
||
Excluding the @samp{crypt} tag from inheritance prevents already encrypted
|
||
text from being encrypted again.
|
||
|
||
@node Hacking
|
||
@appendix Hacking
|
||
|
||
@cindex hacking
|
||
|
||
This appendix describes some ways a user can extend the functionality
|
||
of Org.
|
||
|
||
@menu
|
||
* Hooks: Hooks (2). 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.
|
||
@end menu
|
||
|
||
@node Hooks (2)
|
||
@appendixsec Hooks
|
||
|
||
@cindex 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
|
||
@uref{https://orgmode.org/worg/doc.html#hooks}.
|
||
|
||
@node Add-on Packages
|
||
@appendixsec Add-on Packages
|
||
|
||
@cindex add-on packages
|
||
|
||
Various authors wrote a large number of add-on packages for Org.
|
||
|
||
These packages are not part of Emacs, but they are distributed as
|
||
contributed packages with the separate release available at
|
||
@uref{https://orgmode.org}. See the @samp{contrib/README} file in the source code
|
||
directory for a list of contributed files. Worg page with more
|
||
information is at: @uref{https://orgmode.org/worg/org-contrib/}.
|
||
|
||
@node Adding Hyperlink Types
|
||
@appendixsec Adding Hyperlink Types
|
||
|
||
@cindex hyperlinks, adding new types
|
||
|
||
Org has many built-in hyperlink types (see @ref{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
|
||
|
||
@example
|
||
[[man:printf][The printf manual]]
|
||
@end example
|
||
|
||
@noindent
|
||
The following @samp{org-man.el} file implements it
|
||
|
||
@lisp
|
||
;;; org-man.el - Support for links to man pages in Org mode
|
||
(require 'org)
|
||
|
||
(org-link-set-parameters "man"
|
||
:follow org-man-command
|
||
: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-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-store-link-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 'org-man)
|
||
;;; org-man.el ends here
|
||
@end lisp
|
||
|
||
@noindent
|
||
To activate links to man pages in Org, enter this in the Emacs init
|
||
file:
|
||
|
||
@lisp
|
||
(require 'org-man)
|
||
@end lisp
|
||
|
||
@noindent
|
||
A review of @samp{org-man.el}:
|
||
|
||
@enumerate
|
||
@item
|
||
First, @code{(require 'org)} ensures @samp{org.el} is loaded.
|
||
|
||
@item
|
||
@findex org-link-set-parameters
|
||
@vindex org-link-parameters
|
||
Then @code{org-link-set-parameters} defines a new link type with @samp{man}
|
||
prefix and associates functions for following, exporting and
|
||
storing such links. See the variable @code{org-link-parameters} for
|
||
a complete list of possible associations.
|
||
|
||
@item
|
||
The rest of the file implements necessary variables and functions.
|
||
|
||
For example, @code{org-man-store-link} is responsible for storing a link
|
||
when @code{org-store-link} (see @ref{Handling Links}) is called from a buffer
|
||
displaying a man page. It first checks if the @code{major-mode} is
|
||
appropriate. If check fails, the function returns @code{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 @samp{man:} prefix with the man topic. It also provides a default
|
||
description. The function @code{org-insert-link} can insert it back
|
||
into an Org buffer later on.
|
||
@end enumerate
|
||
|
||
@node Adding Export Back-ends
|
||
@appendixsec Adding Export Back-ends
|
||
|
||
@cindex Export, writing 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.
|
||
|
||
@findex org-export-define-backend
|
||
@findex org-export-define-derived-backend
|
||
The two main entry points to the export engine are:
|
||
@code{org-export-define-backend} and @code{org-export-define-derived-backend}.
|
||
To grok these functions, see @samp{ox-latex.el} for an example of defining
|
||
a new back-end from scratch, and @samp{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 @code{:menu-entry}
|
||
keyword. For export options specific to this back-end, set the
|
||
@code{:options-alist}.
|
||
|
||
For creating a new back-end from an existing one, set
|
||
@code{:translate-alist} to an alist of export functions. This alist
|
||
replaces the parent back-end functions.
|
||
|
||
For complete documentation, see @uref{https://orgmode.org/worg/dev/org-export-reference.html, the Org Export Reference on Worg}.
|
||
|
||
@node Tables in Arbitrary Syntax
|
||
@appendixsec Tables in Arbitrary Syntax
|
||
|
||
@cindex tables, in other modes
|
||
@cindex lists, in other modes
|
||
@cindex Orgtbl mode
|
||
|
||
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 @emph{translate} function that
|
||
operates on a native Org @emph{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.
|
||
@end menu
|
||
|
||
@node Radio tables
|
||
@appendixsubsec Radio tables
|
||
|
||
@cindex 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 @samp{BEGIN/END
|
||
RECEIVE ORGTBL}. They have to appear as comments in the current mode.
|
||
If the mode is C, then:
|
||
|
||
@example
|
||
/* BEGIN RECEIVE ORGTBL table_name */
|
||
/* END RECEIVE ORGTBL table_name */
|
||
@end example
|
||
|
||
@noindent
|
||
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:
|
||
|
||
@cindex @samp{ORGTBL}, keyword
|
||
@example
|
||
#+ORGTBL: SEND table_name translation_function arguments ...
|
||
@end example
|
||
|
||
@noindent
|
||
@samp{table_name} is the table's reference name, which is also used in the
|
||
receiver lines, and the @samp{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:
|
||
|
||
@table @asis
|
||
@item @samp{:skip N}
|
||
Skip the first N lines of the table. Hlines do count; include
|
||
them if they are to be skipped.
|
||
|
||
@item @samp{: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
|
||
@samp{skipcols}.
|
||
@end table
|
||
|
||
@noindent
|
||
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:
|
||
|
||
@itemize
|
||
@item
|
||
Place the table in a block comment. For example, in C mode you
|
||
could wrap the table between @samp{/*} and @samp{*/} lines.
|
||
|
||
@item
|
||
Put the table after an ``end'' statement. For example @code{\bye} in @TeX{}
|
||
and @code{\end@{document@}} in @LaTeX{}.
|
||
|
||
@item
|
||
Comment and un-comment each line of the table during edits. The
|
||
@kbd{M-x orgtbl-toggle-comment} command makes toggling easy.
|
||
@end itemize
|
||
|
||
@node A @LaTeX{} example
|
||
@appendixsubsec A @LaTeX{} example of radio tables
|
||
|
||
@cindex @LaTeX{}, and Orgtbl mode
|
||
|
||
To wrap a source table in @LaTeX{}, use the @samp{comment} environment
|
||
provided by @samp{comment.sty}@footnote{@uref{https://ctan.org/tex-archive/macros/latex/contrib/comment?lang=en}}. To activate it, put
|
||
@code{\usepackage@{comment@}} in the document header. Orgtbl mode inserts
|
||
a radio table skeleton@footnote{Because @samp{LEVEL=2} has 3 stars, @samp{LEVEL=3} has 4 stars, and so
|
||
on.} with the command @kbd{M-x orgtbl-insert-radio-table}, which prompts for a table name. For
|
||
example, if @samp{salesfigures} is the name, the template inserts:
|
||
|
||
@example
|
||
% BEGIN RECEIVE ORGTBL salesfigures
|
||
% END RECEIVE ORGTBL salesfigures
|
||
\begin@{comment@}
|
||
#+ORGTBL: SEND salesfigures orgtbl-to-latex
|
||
| | |
|
||
\end@{comment@}
|
||
@end example
|
||
|
||
@vindex LaTeX-verbatim-environments
|
||
@noindent
|
||
The line @samp{#+ORGTBL: SEND} tells Orgtbl mode to use the function
|
||
@code{orgtbl-to-latex} to convert the table to @LaTeX{} format, then insert
|
||
the table at the target (receive) location named @samp{salesfigures}. Now
|
||
the table is ready for data entry. It can even use spreadsheet
|
||
features@footnote{If the @samp{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 @samp{comment} environment that is used to balance the dollar
|
||
expressions. If you are using AUC@TeX{} with the font-latex library,
|
||
a much better solution is to add the @samp{comment} environment to the
|
||
variable @code{LaTeX-verbatim-environments}.}:
|
||
|
||
@example
|
||
% 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@}
|
||
@end example
|
||
|
||
@noindent
|
||
After editing, @kbd{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
|
||
@emph{splice} out the target table without the header and footer.
|
||
|
||
@example
|
||
\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@}
|
||
@end example
|
||
|
||
The @LaTeX{} translator function @code{orgtbl-to-latex} is already part of
|
||
Orgtbl mode and uses a @samp{tabular} environment to typeset the table and
|
||
marks horizontal lines with @code{\hline}. For additional parameters to
|
||
control output, see @ref{Translator functions}:
|
||
|
||
@table @asis
|
||
@item @code{:splice nil/t}
|
||
When non-@code{nil}, return only table body lines; not wrapped in
|
||
tabular environment. Default is @code{nil}.
|
||
|
||
@item @code{:fmt FMT}
|
||
Format to warp each field. It should contain @samp{%s} for the
|
||
original field value. For example, to wrap each field value in
|
||
dollar symbol, you could use @samp{:fmt "$%s$"}. Format can also wrap
|
||
a property list with column numbers and formats, for example
|
||
@samp{: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.
|
||
|
||
@item @code{:efmt EFMT}
|
||
Format numbers as exponentials. The spec should have @samp{%s} twice
|
||
for inserting mantissa and exponent, for example
|
||
@samp{"%s\\times10^@{%s@}"}. This may also be a property list with
|
||
column numbers and formats, for example @samp{:efmt (2
|
||
"$%s\\times10^@{%s@}$" 4 "$%s\\cdot10^@{%s@}$")}. After
|
||
@var{EFMT} has been applied to a value, @var{FMT}---see
|
||
above---is also be applied. Functions with two arguments can be
|
||
supplied instead of strings. By default, no special formatting
|
||
is applied.
|
||
@end table
|
||
|
||
@node Translator functions
|
||
@appendixsubsec Translator functions
|
||
|
||
@cindex HTML, and Orgtbl mode
|
||
@cindex translator function
|
||
|
||
@findex orgtbl-to-csv
|
||
@findex orgtbl-to-tsv
|
||
@findex orgtbl-to-latex
|
||
@findex orgtbl-to-html
|
||
@findex orgtbl-to-texinfo
|
||
@findex orgtbl-to-unicode
|
||
@findex orgtbl-to-orgtbl
|
||
@findex orgtbl-to-generic
|
||
Orgtbl mode has built-in translator functions: @code{orgtbl-to-csv}
|
||
(comma-separated values), @code{orgtbl-to-tsv} (TAB-separated values),
|
||
@code{orgtbl-to-latex}, @code{orgtbl-to-html}, @code{orgtbl-to-texinfo},
|
||
@code{orgtbl-to-unicode} and @code{orgtbl-to-orgtbl}. They use the generic
|
||
translator, @code{orgtbl-to-generic}, which delegates translations to
|
||
various export back-ends.
|
||
|
||
Properties passed to the function through the @samp{ORGTBL SEND} line take
|
||
precedence over properties defined inside the function. For example,
|
||
this overrides the default @LaTeX{} line endings, @code{\\}, with @code{\\[2mm]}:
|
||
|
||
@example
|
||
#+ORGTBL: SEND test orgtbl-to-latex :lend " \\\\[2mm]"
|
||
@end example
|
||
|
||
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 @samp{!BTBL!} and @samp{!ETBL!};
|
||
a beginning and ending of lines with @samp{!BL!} and @samp{!EL!}; and uses a TAB
|
||
for a field separator:
|
||
|
||
@lisp
|
||
(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)))
|
||
@end lisp
|
||
|
||
@noindent
|
||
The documentation for the @code{orgtbl-to-generic} function shows
|
||
a complete list of parameters, each of which can be passed through to
|
||
@code{orgtbl-to-latex}, @code{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 @code{hline}. The second argument is the property
|
||
list consisting of parameters specified in the @samp{#+ORGTBL: SEND} line.
|
||
Please share your translator functions by posting them to the Org
|
||
users mailing list, at @email{emacs-orgmode@@gnu.org}.
|
||
|
||
@node Dynamic Blocks
|
||
@appendixsec Dynamic Blocks
|
||
|
||
@cindex dynamic blocks
|
||
|
||
Org supports @emph{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. For example, @kbd{C-c C-x C-r} inserts a dynamic table that updates the work time (see
|
||
@ref{Clocking Work Time}).
|
||
|
||
Dynamic blocks can have names and function parameters. The syntax is
|
||
similar to source code block specifications:
|
||
|
||
@example
|
||
#+BEGIN: myblock :parameter1 value1 :parameter2 value2 ...
|
||
...
|
||
#+END:
|
||
@end example
|
||
|
||
These commands update dynamic blocks:
|
||
|
||
@table @asis
|
||
@item @kbd{C-c C-x C-u} (@code{org-dblock-update})
|
||
@kindex C-c C-x C-u
|
||
@findex org-dblock-update
|
||
Update dynamic block at point.
|
||
|
||
@item @kbd{C-u C-c C-x C-u}
|
||
@kindex C-u C-c C-x C-u
|
||
Update all dynamic blocks in the current file.
|
||
@end table
|
||
|
||
Before updating a dynamic block, Org removes content between the
|
||
@samp{BEGIN} and @samp{END} markers. Org then reads the parameters on the
|
||
@samp{BEGIN} line for passing to the writer function. If the function
|
||
expects to access the removed content, then Org expects an extra
|
||
parameter, @samp{:content}, on the @samp{BEGIN} line.
|
||
|
||
The syntax for naming a writer function with a dynamic block labelled
|
||
@samp{myblock} is: @code{org-dblock-write:myblock}. Parameters come from the
|
||
@samp{BEGIN} line.
|
||
|
||
The following is an example of a dynamic block and a block writer function
|
||
that updates the time when the function was last run:
|
||
|
||
@example
|
||
#+BEGIN: block-update-time :format "on %m/%d/%Y at %H:%M"
|
||
...
|
||
#+END:
|
||
@end example
|
||
|
||
@noindent
|
||
The dynamic block's writer function:
|
||
|
||
@lisp
|
||
(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))))
|
||
@end lisp
|
||
|
||
To keep dynamic blocks up-to-date in an Org file, use the function,
|
||
@code{org-update-all-dblocks} in hook, such as @code{before-save-hook}. The
|
||
@code{org-update-all-dblocks} function does not run if the file is not in
|
||
Org mode.
|
||
|
||
@findex org-narrow-to-block
|
||
Dynamic blocks, like any other block, can be narrowed with
|
||
@code{org-narrow-to-block}.
|
||
|
||
@node Special Agenda Views
|
||
@appendixsec Special Agenda Views
|
||
|
||
@cindex agenda views, user-defined
|
||
|
||
@vindex org-agenda-skip-function
|
||
@vindex org-agenda-skip-function-global
|
||
Org provides a special hook to further limit items in agenda views:
|
||
@code{agenda}, @code{agenda*}@footnote{The @code{agenda*} view is the same as @code{agenda} except that it
|
||
only considers @emph{appointments}, i.e., scheduled and deadline items that
|
||
have a time specification @samp{[h]h:mm} in their time-stamps.}, @code{todo}, @code{alltodo}, @code{tags}, @code{tags-todo},
|
||
@code{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
|
||
@code{org-agenda-skip-function-global} variable. Org uses a global
|
||
condition with @code{org-agenda-skip-function} for custom searching.
|
||
|
||
This example defines a function for a custom view showing TODO items
|
||
with @samp{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 @samp{waiting} tag and
|
||
returns @code{nil} on match. Otherwise it gives the location from where
|
||
the search continues.
|
||
|
||
@lisp
|
||
(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
|
||
@end lisp
|
||
|
||
To use this custom function in a custom agenda command:
|
||
|
||
@lisp
|
||
(org-add-agenda-custom-command
|
||
'("b" todo "PROJECT"
|
||
((org-agenda-skip-function 'my-skip-unless-waiting)
|
||
(org-agenda-overriding-header "Projects waiting for something: "))))
|
||
@end lisp
|
||
|
||
@vindex org-agenda-overriding-header
|
||
Note that this also binds @code{org-agenda-overriding-header} to a more
|
||
meaningful string suitable for the agenda view.
|
||
|
||
@vindex org-odd-levels-only
|
||
@vindex org-agenda-skip-function
|
||
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 @samp{LEVEL>0}@footnote{Note that, for @code{org-odd-levels-only}, a level number
|
||
corresponds to order in the hierarchy, not to the number of stars.}. Then to selectively pick
|
||
the matched entries, use @code{org-agenda-skip-function}, which also
|
||
accepts Lisp forms, such as @code{org-agenda-skip-entry-if} and
|
||
@code{org-agenda-skip-subtree-if}. For example:
|
||
|
||
@table @asis
|
||
@item @code{(org-agenda-skip-entry-if 'scheduled)}
|
||
Skip current entry if it has been scheduled.
|
||
|
||
@item @code{(org-agenda-skip-entry-if 'notscheduled)}
|
||
Skip current entry if it has not been scheduled.
|
||
|
||
@item @code{(org-agenda-skip-entry-if 'deadline)}
|
||
Skip current entry if it has a deadline.
|
||
|
||
@item @code{(org-agenda-skip-entry-if 'scheduled 'deadline)}
|
||
Skip current entry if it has a deadline, or if it is scheduled.
|
||
|
||
@item @code{(org-agenda-skip-entry-if 'todo '("TODO" "WAITING"))}
|
||
Skip current entry if the TODO keyword is TODO or WAITING.
|
||
|
||
@item @code{(org-agenda-skip-entry-if 'todo 'done)}
|
||
Skip current entry if the TODO keyword marks a DONE state.
|
||
|
||
@item @code{(org-agenda-skip-entry-if 'timestamp)}
|
||
Skip current entry if it has any timestamp, may also be deadline
|
||
or scheduled.
|
||
|
||
@item @code{(org-agenda-skip-entry-if 'regexp "regular expression")}
|
||
Skip current entry if the regular expression matches in the
|
||
entry.
|
||
|
||
@item @code{(org-agenda-skip-entry-if 'notregexp "regular expression")}
|
||
Skip current entry unless the regular expression matches.
|
||
|
||
@item @code{(org-agenda-skip-subtree-if 'regexp "regular expression")}
|
||
Same as above, but check and skip the entire subtree.
|
||
@end table
|
||
|
||
The following is an example of a search for @samp{waiting} without the
|
||
special function:
|
||
|
||
@lisp
|
||
(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: "))))
|
||
@end lisp
|
||
|
||
@node Speeding Up Your Agendas
|
||
@appendixsec Speeding Up Your Agendas
|
||
|
||
@cindex agenda views, optimization
|
||
|
||
Some agenda commands slow down when the Org files grow in size or
|
||
number. Here are tips to speed up:
|
||
|
||
@itemize
|
||
@item
|
||
Reduce the number of Org agenda files to avoid slowdowns due to hard drive
|
||
accesses.
|
||
|
||
@item
|
||
Reduce the number of DONE and archived headlines so agenda
|
||
operations that skip over these can finish faster.
|
||
|
||
@item
|
||
Do not dim blocked tasks:
|
||
@vindex org-agenda-dim-blocked-tasks
|
||
|
||
@lisp
|
||
(setq org-agenda-dim-blocked-tasks nil)
|
||
@end lisp
|
||
|
||
@item
|
||
Stop preparing agenda buffers on startup:
|
||
@vindex org-startup-folded
|
||
@vindex org-agenda-inhibit-startup
|
||
|
||
@lisp
|
||
(setq org-agenda-inhibit-startup nil)
|
||
@end lisp
|
||
|
||
@item
|
||
Disable tag inheritance for agendas:
|
||
@vindex org-agenda-show-inherited-tags
|
||
@vindex org-agenda-use-tag-inheritance
|
||
|
||
@lisp
|
||
(setq org-agenda-use-tag-inheritance nil)
|
||
@end lisp
|
||
@end itemize
|
||
|
||
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 @uref{https://orgmode.org/worg/agenda-optimization.html, dedicated Worg page} for agenda
|
||
optimization.
|
||
|
||
@node Extracting Agenda Information
|
||
@appendixsec Extracting Agenda Information
|
||
|
||
@cindex agenda, pipe
|
||
@cindex scripts, for agenda processing
|
||
|
||
Org provides commands to access agendas through Emacs batch mode.
|
||
Through this command-line interface, agendas are automated for further
|
||
processing or printing.
|
||
|
||
@vindex org-agenda-custom-commands
|
||
@findex org-batch-agenda
|
||
@code{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
|
||
@code{org-agenda-custom-commands}. These are the same ones available
|
||
through the agenda dispatcher (see @ref{Agenda Dispatcher}).
|
||
|
||
This example command line directly prints the TODO list to the printer:
|
||
|
||
@example
|
||
emacs -batch -l ~/.emacs -eval '(org-batch-agenda "t")' | lpr
|
||
@end example
|
||
|
||
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 @samp{shop}, but excludes items tagged with
|
||
@samp{NewYork}:
|
||
|
||
@example
|
||
emacs -batch -l ~/.emacs \
|
||
-eval '(org-batch-agenda "+shop-NewYork")' | lpr
|
||
@end example
|
||
|
||
@noindent
|
||
An example showing on-the-fly parameter modifications:
|
||
|
||
@example
|
||
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
|
||
@end example
|
||
|
||
@noindent
|
||
which produces an agenda for the next 30 days from just the
|
||
@samp{~/org/projects.org} file.
|
||
|
||
@findex org-batch-agenda-csv
|
||
For structured processing of agenda output, use @code{org-batch-agenda-csv}
|
||
with the following fields:
|
||
|
||
@table @asis
|
||
@item category
|
||
The category of the item
|
||
@item head
|
||
The headline, without TODO keyword, TAGS and PRIORITY
|
||
@item type
|
||
The type of the agenda entry, can be
|
||
|
||
@multitable {aaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
|
||
@item @code{todo}
|
||
@tab selected in TODO match
|
||
@item @code{tagsmatch}
|
||
@tab selected in tags match
|
||
@item @code{diary}
|
||
@tab imported from diary
|
||
@item @code{deadline}
|
||
@tab a deadline
|
||
@item @code{scheduled}
|
||
@tab scheduled
|
||
@item @code{timestamp}
|
||
@tab appointment, selected by timestamp
|
||
@item @code{closed}
|
||
@tab entry was closed on date
|
||
@item @code{upcoming-deadline}
|
||
@tab warning about nearing deadline
|
||
@item @code{past-scheduled}
|
||
@tab forwarded scheduled item
|
||
@item @code{block}
|
||
@tab entry has date block including date
|
||
@end multitable
|
||
|
||
@item todo
|
||
The TODO keyword, if any
|
||
@item tags
|
||
All tags including inherited ones, separated by colons
|
||
@item date
|
||
The relevant date, like @samp{2007-2-14}
|
||
@item time
|
||
The time, like @samp{15:00-16:50}
|
||
@item extra
|
||
String with extra planning info
|
||
@item priority-l
|
||
The priority letter if any was given
|
||
@item priority-n
|
||
The computed numerical priority
|
||
@end table
|
||
|
||
@noindent
|
||
If the selection of the agenda item was based on a timestamp,
|
||
including those items with @samp{DEADLINE} and @samp{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:
|
||
|
||
@example
|
||
#!/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";
|
||
@}
|
||
@end example
|
||
|
||
@node Using the Property API
|
||
@appendixsec Using the Property API
|
||
|
||
@cindex API, for properties
|
||
@cindex properties, API
|
||
|
||
Here is a description of the functions that can be used to work with
|
||
properties.
|
||
|
||
@defun org-entry-properties &optional pom which
|
||
Get all properties of the entry at point-or-marker @var{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. @var{POM} may also
|
||
be @code{nil}, in which case the current entry is used. If
|
||
@var{WHICH} is @code{nil} or @code{all}, get all properties. If
|
||
@var{WHICH} is @code{special} or @code{standard}, only get that subclass.
|
||
@end defun
|
||
|
||
@vindex org-use-property-inheritance
|
||
@findex org-insert-property-drawer
|
||
@defun org-entry-get pom property &optional inherit
|
||
Get value of @var{PROPERTY} for entry at point-or-marker
|
||
@var{POM}. By default, this only looks at properties defined
|
||
locally in the entry. If @var{INHERIT} is non-@code{nil} and the
|
||
entry does not have the property, then also check higher levels of the
|
||
hierarchy. If @var{INHERIT} is the symbol @code{selective}, use
|
||
inheritance if and only if the setting of
|
||
@code{org-use-property-inheritance} selects @var{PROPERTY} for
|
||
inheritance.
|
||
@end defun
|
||
|
||
@defun org-entry-delete pom property
|
||
Delete the property @var{PROPERTY} from entry at point-or-marker
|
||
@var{POM}.
|
||
@end defun
|
||
|
||
@defun org-entry-put pom property value
|
||
Set @var{PROPERTY} to @var{VALUES} for entry at
|
||
point-or-marker POM.
|
||
@end defun
|
||
|
||
@defun org-buffer-property-keys &optional include-specials
|
||
Get all property keys in the current buffer.
|
||
@end defun
|
||
|
||
@defun org-insert-property-drawer
|
||
Insert a property drawer for the current entry. Also
|
||
@end defun
|
||
|
||
@defun org-entry-put-multivalued-property pom property &rest values
|
||
Set @var{PROPERTY} at point-or-marker @var{POM} to
|
||
@var{VALUES}. @var{VALUES} should be a list of strings.
|
||
They are concatenated, with spaces as separators.
|
||
@end defun
|
||
|
||
@defun org-entry-get-multivalued-property pom property
|
||
Treat the value of the property @var{PROPERTY} as
|
||
a whitespace-separated list of values and return the values as a list
|
||
of strings.
|
||
@end defun
|
||
|
||
@defun org-entry-add-to-multivalued-property pom property value
|
||
Treat the value of the property @var{PROPERTY} as
|
||
a whitespace-separated list of values and make sure that
|
||
@var{VALUE} is in this list.
|
||
@end defun
|
||
|
||
@defun org-entry-remove-from-multivalued-property pom property value
|
||
Treat the value of the property @var{PROPERTY} as
|
||
a whitespace-separated list of values and make sure that
|
||
@var{VALUE} is @emph{not} in this list.
|
||
@end defun
|
||
|
||
@defun org-entry-member-in-multivalued-property pom property value
|
||
Treat the value of the property @var{PROPERTY} as
|
||
a whitespace-separated list of values and check if @var{VALUE} is
|
||
in this list.
|
||
@end defun
|
||
|
||
@defopt 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 @samp{:ETC} is one of the
|
||
values, use the values as completion help, but allow also other values
|
||
to be entered. The functions must return @code{nil} if they are not
|
||
responsible for this property.
|
||
@end defopt
|
||
|
||
@node Using the Mapping API
|
||
@appendixsec Using the Mapping API
|
||
|
||
@cindex API, for mapping
|
||
@cindex mapping entries, 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:
|
||
|
||
@defun org-map-entries func &optional match scope &rest skip
|
||
Call @{@{@{(var(FUNC))@}@}@} at each headline selected by @var{MATCH}
|
||
in @var{SCOPE}.
|
||
|
||
@var{FUNC} is a function or a Lisp form. With the cursor
|
||
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 @var{FUNC} in
|
||
save-excursion form. After evaluation, Org moves the cursor 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
|
||
@var{FUNC} set the variable @code{org-map-continue-from} to a specific
|
||
buffer position.
|
||
|
||
@var{MATCH} is a tags/property/TODO match. Org iterates only
|
||
matched headlines. Org iterates over all headlines when
|
||
@var{MATCH} is @code{nil} or @code{t}.
|
||
|
||
@var{SCOPE} determines the scope of this command. It can be any
|
||
of:
|
||
|
||
@table @asis
|
||
@item @code{nil}
|
||
The current buffer, respecting the restriction, if any.
|
||
|
||
@item @code{tree}
|
||
The subtree started with the entry at point.
|
||
|
||
@item @code{region}
|
||
The entries within the active region, if any.
|
||
|
||
@item @code{file}
|
||
The current buffer, without restriction.
|
||
|
||
@item @code{file-with-archives}
|
||
The current buffer, and any archives associated with it.
|
||
|
||
@item @code{agenda}
|
||
All agenda files.
|
||
|
||
@item @code{agenda-with-archives}
|
||
All agenda files with any archive files associated with them.
|
||
|
||
@item @code{(file1 file2 ...)}
|
||
If this is a list, all files in the list are scanned.
|
||
@end table
|
||
|
||
@noindent
|
||
The remaining arguments are treated as settings for the scanner's
|
||
skipping facilities. Valid arguments are:
|
||
|
||
@table @asis
|
||
@item @code{archive}
|
||
Skip trees with the archive tag.
|
||
|
||
@item @code{comment}
|
||
Skip trees with the COMMENT keyword.
|
||
|
||
@item function or Lisp form
|
||
@vindex org-agenda-skip-function
|
||
Used as value for @code{org-agenda-skip-function}, so whenever the
|
||
function returns @code{t}, @var{FUNC} is called for that entry
|
||
and search continues from the point where the function leaves it.
|
||
@end table
|
||
@end defun
|
||
|
||
The mapping routine can call any arbitrary function, even functions
|
||
that change meta data or query the property API (see @ref{Using the Property API}). Here are some handy functions:
|
||
|
||
@defun 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
|
||
@var{ARG}.
|
||
@end defun
|
||
|
||
@defun org-priority &optional action
|
||
Change the priority of the entry. See the docstring of this function
|
||
for the possible values for @var{ACTION}.
|
||
@end defun
|
||
|
||
@defun org-toggle-tag tag &optional onoff
|
||
Toggle the tag @var{TAG} in the current entry. Setting
|
||
@var{ONOFF} to either @code{on} or @code{off} does not toggle tag, but
|
||
ensure that it is either on or off.
|
||
@end defun
|
||
|
||
@defun org-promote
|
||
Promote the current entry.
|
||
@end defun
|
||
|
||
@defun org-demote
|
||
Demote the current entry.
|
||
@end defun
|
||
|
||
This example turns all entries tagged with @samp{TOMORROW} into TODO
|
||
entries with keyword @samp{UPCOMING}. Org ignores entries in comment trees
|
||
and archive trees.
|
||
|
||
@lisp
|
||
(org-map-entries '(org-todo "UPCOMING")
|
||
"+TOMORROW" 'file 'archive 'comment)
|
||
@end lisp
|
||
|
||
The following example counts the number of entries with TODO keyword
|
||
@samp{WAITING}, in all agenda files.
|
||
|
||
@lisp
|
||
(length (org-map-entries t "/+WAITING" 'agenda))
|
||
@end lisp
|
||
|
||
@node MobileOrg
|
||
@appendix MobileOrg
|
||
|
||
@cindex iPhone
|
||
@cindex smartphone
|
||
@cindex android
|
||
@cindex MobileOrg
|
||
|
||
MobileOrg is a companion mobile app that runs on iOS and Android
|
||
devices. MobileOrg enables offline-views and capture support for an
|
||
Org mode system that is rooted on a ``real'' computer. MobileOrg can
|
||
record changes to existing entries.
|
||
|
||
The @uref{https://github.com/MobileOrg/, iOS implementation} for the @emph{iPhone/iPod Touch/iPad} series of
|
||
devices, was started by Richard Moreland and is now in the hands of
|
||
Sean Escriva. Android users should check out @uref{http://wiki.github.com/matburt/mobileorg-android/, MobileOrg Android} by
|
||
Matt Jones. Though the two implementations are not identical, they
|
||
offer similar features.
|
||
|
||
This appendix describes Org's support for agenda view formats
|
||
compatible with MobileOrg. It also describes synchronizing changes,
|
||
such as to notes, between MobileOrg and the computer.
|
||
|
||
To change tags and TODO states in MobileOrg, first customize the
|
||
variables @code{org-todo-keywords} and @code{org-tag-alist}. These should cover
|
||
all the important tags and TODO keywords, even if Org files use only
|
||
some of them. Though MobileOrg has in-buffer settings, it understands
|
||
TODO states @emph{sets} (see @ref{Per-file keywords}) and
|
||
@emph{mutually exclusive} tags (see @ref{Setting Tags}) only for those set in
|
||
these variables.
|
||
|
||
@menu
|
||
* Setting Up the Staging Area:: For the mobile device.
|
||
* Pushing to MobileOrg:: Uploading Org files and agendas.
|
||
* Pulling from MobileOrg:: Integrating captured and flagged items.
|
||
@end menu
|
||
|
||
@node Setting Up the Staging Area
|
||
@appendixsec Setting Up the Staging Area
|
||
|
||
MobileOrg needs access to a file directory on a server to interact
|
||
with Emacs. With a public server, consider encrypting the files.
|
||
MobileOrg version 1.5 supports encryption for the iPhone. Org also
|
||
requires @samp{openssl} installed on the local computer. To turn on
|
||
encryption, set the same password in MobileOrg and in Emacs. Set the
|
||
password in the variable @code{org-mobile-use-encryption}@footnote{If Emacs is configured for safe storing of passwords, then
|
||
configure the variable, @code{org-mobile-encryption-password}; please read
|
||
the docstring of that variable.}. Note
|
||
that even after MobileOrg encrypts the file contents, the file name
|
||
remains visible on the file systems of the local computer, the server,
|
||
and the mobile device.
|
||
|
||
For a server to host files, consider options like @uref{http://dropbox.com, Dropbox.com}
|
||
account@footnote{An alternative is to use a WebDAV server. MobileOrg
|
||
documentation has details of WebDAV server configuration. Additional
|
||
help is at this @uref{https://orgmode.org/worg/org-faq.html#mobileorg_webdav, FAQ entry}.}. On first connection, MobileOrg creates a directory
|
||
@samp{MobileOrg} on Dropbox. Pass its location to Emacs through an
|
||
initialisation file variable as follows:
|
||
|
||
@lisp
|
||
(setq org-mobile-directory "~/Dropbox/MobileOrg")
|
||
@end lisp
|
||
|
||
Org copies files to the above directory for MobileOrg. Org also uses
|
||
the same directory for sharing notes between Org and MobileOrg.
|
||
|
||
@node Pushing to MobileOrg
|
||
@appendixsec Pushing to MobileOrg
|
||
|
||
@vindex org-mobile-files
|
||
@vindex org-directory
|
||
Org pushes files listed in @code{org-mobile-files} to
|
||
@code{org-mobile-directory}. Files include agenda files (as listed in
|
||
@code{org-agenda-files}). Customize @code{org-mobile-files} to add other files.
|
||
File names are staged with paths relative to @code{org-directory}, so all
|
||
files should be inside this directory@footnote{Symbolic links in @code{org-directory} need to have the same name
|
||
as their targets.}.
|
||
|
||
Push creates a special Org file @samp{agendas.org} with custom agenda views
|
||
defined by the user@footnote{While creating the agendas, Org mode forces ID properties on
|
||
all referenced entries, so that these entries can be uniquely
|
||
identified if MobileOrg flags them for further action. To avoid
|
||
setting properties configure the variable
|
||
@code{org-mobile-force-id-on-agenda-items} to @code{nil}. Org mode then relies
|
||
on outline paths, assuming they are unique.}.
|
||
|
||
Finally, Org writes the file @samp{index.org}, containing links to other
|
||
files. MobileOrg reads this file first from the server to determine
|
||
what other files to download for agendas. For faster downloads,
|
||
MobileOrg only reads files whose checksums@footnote{Checksums are stored automatically in the file
|
||
@samp{checksums.dat}.} have changed.
|
||
|
||
@node Pulling from MobileOrg
|
||
@appendixsec Pulling from MobileOrg
|
||
|
||
When MobileOrg synchronizes with the server, it pulls the Org files
|
||
for viewing. It then appends to the file @samp{mobileorg.org} on the
|
||
server the captured entries, pointers to flagged and changed entries.
|
||
Org integrates its data in an inbox file format.
|
||
|
||
@enumerate
|
||
@item
|
||
@vindex org-mobile-inbox-for-pull
|
||
Org moves all entries found in @samp{mobileorg.org}@footnote{The file will be empty after this operation.} and appends
|
||
them to the file pointed to by the variable
|
||
@code{org-mobile-inbox-for-pull}. Each captured entry and each editing
|
||
event is a top-level entry in the inbox file.
|
||
|
||
@item
|
||
After moving the entries, Org attempts changes to MobileOrg. Some
|
||
changes are applied directly and without user interaction.
|
||
Examples include changes to tags, TODO state, headline and body
|
||
text. Entries for further action are tagged as @samp{FLAGGED}. Org
|
||
marks entries with problems with an error message in the inbox.
|
||
They have to be resolved manually.
|
||
|
||
@item
|
||
Org generates an agenda view for flagged entries for user
|
||
intervention to clean up. For notes stored in flagged entries,
|
||
MobileOrg displays them in the echo area when the cursor is on the
|
||
corresponding agenda item.
|
||
|
||
@table @asis
|
||
@item @kbd{?}
|
||
@kindex ?
|
||
|
||
Pressing @kbd{?} 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 @kbd{? z C-y C-c C-c}. Pressing@kbd{?} twice does these things: first
|
||
it removes the @samp{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.
|
||
@end table
|
||
@end enumerate
|
||
|
||
@kindex ? @r{(Agenda dispatcher)}
|
||
From the agenda dispatcher, @kbd{?} returns to the view to finish
|
||
processing flagged entries. Note that these entries may not be the
|
||
most recent since MobileOrg searches files that were last pulled. To
|
||
get an updated agenda view with changes since the last pull, pull
|
||
again.
|
||
|
||
@node History and Acknowledgments
|
||
@appendix History and Acknowledgments
|
||
|
||
|
||
|
||
@anchor{From Carsten}
|
||
@appendixsec 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. @emph{Visibility cycling}
|
||
and @emph{structure editing} were originally implemented in the package
|
||
@samp{outline-magic.el}, but quickly moved to the more general @samp{org.el}.
|
||
As this environment became comfortable for project planning, the next
|
||
step was adding @emph{TODO entries}, basic @emph{timestamps}, and @emph{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
|
||
@email{emacs-orgmode@@gnu.org, mailing list} 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:
|
||
|
||
@table @asis
|
||
@item 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.
|
||
|
||
@item 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.
|
||
|
||
@item John Wiegley
|
||
John has contributed a number of great ideas and patches directly
|
||
to Org, including the attachment system (@samp{org-attach.el}),
|
||
integration with Apple Mail (@samp{org-mac-message.el}), hierarchical
|
||
dependencies of TODO items, habit tracking (@samp{org-habits.el}), and
|
||
encryption (@samp{org-crypt.el}). Also, the capture system is really
|
||
an extended copy of his great @samp{remember.el}.
|
||
|
||
@item 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
|
||
@samp{org-info.js}, a Java script for displaying webpages derived from
|
||
Org using an Info-like or a folding interface with single-key
|
||
navigation.
|
||
@end table
|
||
|
||
@noindent
|
||
See below for the full list of contributions! Again, please let me
|
||
know what I am missing here!
|
||
|
||
@anchor{From Bastien}
|
||
@appendixsec 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:
|
||
|
||
@table @asis
|
||
@item 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.
|
||
|
||
@item Nicolas Goaziou
|
||
Nicolas is maintaining the consistency of the deepest parts of
|
||
Org. His work on @samp{org-element.el} and @samp{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.
|
||
|
||
@item Achim Gratz
|
||
Achim rewrote the building process of Org, turning some @emph{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.
|
||
|
||
@item 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.
|
||
@end table
|
||
|
||
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.
|
||
|
||
@anchor{List of Contributions}
|
||
@appendixsec List of Contributions
|
||
|
||
@itemize
|
||
@item
|
||
Russel Adams came up with the idea for drawers.
|
||
|
||
@item
|
||
Thomas Baumann wrote @samp{org-bbdb.el} and @samp{org-mhe.el}.
|
||
|
||
@item
|
||
Christophe Bataillon created the great unicorn logo that we use on
|
||
the Org mode website.
|
||
|
||
@item
|
||
Alex Bochannek provided a patch for rounding timestamps.
|
||
|
||
@item
|
||
Jan Böcker wrote @samp{org-docview.el}.
|
||
|
||
@item
|
||
Brad Bozarth showed how to pull RSS feed data into Org files.
|
||
|
||
@item
|
||
Tom Breton wrote @samp{org-choose.el}.
|
||
|
||
@item
|
||
Charles Cave's suggestion sparked the implementation of templates
|
||
for Remember, which are now templates for capture.
|
||
|
||
@item
|
||
Pavel Chalmoviansky influenced the agenda treatment of items with
|
||
specified time.
|
||
|
||
@item
|
||
Gregory Chernov patched support for Lisp forms into table
|
||
calculations and improved XEmacs compatibility, in particular by
|
||
porting @samp{nouline.el} to XEmacs.
|
||
|
||
@item
|
||
Sacha Chua suggested copying some linking code from Planner.
|
||
|
||
@item
|
||
Baoqiu Cui contributed the DocBook exporter.
|
||
|
||
@item
|
||
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.
|
||
|
||
@item
|
||
Nick Dokos tracked down several nasty bugs.
|
||
|
||
@item
|
||
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.
|
||
|
||
@item
|
||
Thomas S. Dye contributed documentation on Worg and helped
|
||
integrating the Org Babel documentation into the manual.
|
||
|
||
@item
|
||
Christian Egli converted the documentation into Texinfo format,
|
||
inspired the agenda, patched CSS formatting into the HTML exporter,
|
||
and wrote @samp{org-taskjuggler.el}.
|
||
|
||
@item
|
||
David Emery provided a patch for custom CSS support in exported HTML
|
||
agendas.
|
||
|
||
@item
|
||
Nic Ferrier contributed mailcap and XOXO support.
|
||
|
||
@item
|
||
Miguel A. Figueroa-Villanueva implemented hierarchical checkboxes.
|
||
|
||
@item
|
||
John Foerch figured out how to make incremental search show context
|
||
around a match in a hidden outline tree.
|
||
|
||
@item
|
||
Raimar Finken wrote @samp{org-git-line.el}.
|
||
|
||
@item
|
||
Mikael Fornius works as a mailing list moderator.
|
||
|
||
@item
|
||
Austin Frank works as a mailing list moderator.
|
||
|
||
@item
|
||
Eric Fraga drove the development of Beamer export with ideas and
|
||
testing.
|
||
|
||
@item
|
||
Barry Gidden did proofreading the manual in preparation for the book
|
||
publication through Network Theory Ltd.
|
||
|
||
@item
|
||
Niels Giesen had the idea to automatically archive DONE trees.
|
||
|
||
@item
|
||
Nicolas Goaziou rewrote much of the plain list code.
|
||
|
||
@item
|
||
Kai Grossjohann pointed out key-binding conflicts with other
|
||
packages.
|
||
|
||
@item
|
||
Brian Gough of Network Theory Ltd publishes the Org mode manual as
|
||
a book.
|
||
|
||
@item
|
||
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.
|
||
|
||
@item
|
||
Manuel Hermenegildo has contributed various ideas, small fixes and
|
||
patches.
|
||
|
||
@item
|
||
Phil Jackson wrote @samp{org-irc.el}.
|
||
|
||
@item
|
||
Scott Jaderholm proposed footnotes, control over whitespace between
|
||
folded entries, and column view for properties.
|
||
|
||
@item
|
||
Matt Jones wrote MobileOrg Android.
|
||
|
||
@item
|
||
Tokuya Kameshima wrote @samp{org-wl.el} and @samp{org-mew.el}.
|
||
|
||
@item
|
||
Shidai Liu (``Leo'') asked for embedded @LaTeX{} and tested it. He also
|
||
provided frequent feedback and some patches.
|
||
|
||
@item
|
||
Matt Lundin has proposed last-row references for table formulas and
|
||
named invisible anchors. He has also worked a lot on the FAQ.
|
||
|
||
@item
|
||
David Maus wrote @samp{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.
|
||
|
||
@item
|
||
Jason F. McBrayer suggested agenda export to CSV format.
|
||
|
||
@item
|
||
Max Mikhanosha came up with the idea of refiling.
|
||
|
||
@item
|
||
Dmitri Minaev sent a patch to set priority limits on a per-file
|
||
basis.
|
||
|
||
@item
|
||
Stefan Monnier provided a patch to keep the Emacs Lisp compiler
|
||
happy.
|
||
|
||
@item
|
||
Richard Moreland wrote MobileOrg for the iPhone.
|
||
|
||
@item
|
||
Rick Moynihan proposed allowing multiple TODO sequences in a file
|
||
and being able to quickly restrict the agenda to a subtree.
|
||
|
||
@item
|
||
Todd Neal provided patches for links to Info files and Elisp forms.
|
||
|
||
@item
|
||
Greg Newman refreshed the unicorn logo into its current form.
|
||
|
||
@item
|
||
Tim O'Callaghan suggested in-file links, search options for general
|
||
file links, and tags.
|
||
|
||
@item
|
||
Osamu Okano wrote @samp{orgcard2ref.pl}, a Perl program to create a text
|
||
version of the reference card.
|
||
|
||
@item
|
||
Takeshi Okano translated the manual and David O'Toole's tutorial
|
||
into Japanese.
|
||
|
||
@item
|
||
Oliver Oppitz suggested multi-state TODO items.
|
||
|
||
@item
|
||
Scott Otterson sparked the introduction of descriptive text for
|
||
links, among other things.
|
||
|
||
@item
|
||
Pete Phillips helped during the development of the TAGS feature,
|
||
and provided frequent feedback.
|
||
|
||
@item
|
||
Martin Pohlack provided the code snippet to bundle character
|
||
insertion into bundles of 20 for undo.
|
||
|
||
@item
|
||
T.V. Raman reported bugs and suggested improvements.
|
||
|
||
@item
|
||
Matthias Rempe (Oelde) provided ideas, Windows support, and quality
|
||
control.
|
||
|
||
@item
|
||
Paul Rivier provided the basic implementation of named footnotes.
|
||
He also acted as mailing list moderator for some time.
|
||
|
||
@item
|
||
Kevin Rogers contributed code to access VM files on remote hosts.
|
||
|
||
@item
|
||
Frank Ruell solved the mystery of the @samp{keymapp nil} bug, a conflict
|
||
with @samp{allout.el}.
|
||
|
||
@item
|
||
Jason Riedy generalized the send-receive mechanism for Orgtbl
|
||
tables with extensive patches.
|
||
|
||
@item
|
||
Philip Rooke created the Org reference card, provided lots of
|
||
feedback, developed and applied standards to the Org documentation.
|
||
|
||
@item
|
||
Christian Schlauer proposed angular brackets around links, among
|
||
other things.
|
||
|
||
@item
|
||
Paul Sexton wrote @samp{org-ctags.el}.
|
||
|
||
@item
|
||
Tom Shannon's @samp{organizer-mode.el} inspired linking to VM/BBDB/Gnus.
|
||
|
||
@item
|
||
Ilya Shlyakhter proposed the Archive Sibling, line numbering in
|
||
literal examples, and remote highlighting for referenced code lines.
|
||
|
||
@item
|
||
Stathis Sideris wrote the @samp{ditaa.jar} ASCII to PNG converter that is
|
||
now packaged into Org's @samp{contrib/} directory.
|
||
|
||
@item
|
||
Daniel Sinder came up with the idea of internal archiving by locking
|
||
subtrees.
|
||
|
||
@item
|
||
Dale Smith proposed link abbreviations.
|
||
|
||
@item
|
||
James TD Smith has contributed a large number of patches for
|
||
useful tweaks and features.
|
||
|
||
@item
|
||
Adam Spiers asked for global linking commands, inspired the link
|
||
extension system, added support for Mairix, and proposed the mapping
|
||
API.
|
||
|
||
@item
|
||
Ulf Stegemann created the table to translate special symbols to
|
||
HTML, @LaTeX{}, UTF-8, Latin-1 and ASCII.
|
||
|
||
@item
|
||
Andy Stewart contributed code to @samp{org-w3m.el}, to copy
|
||
HTML content with links transformation to Org syntax.
|
||
|
||
@item
|
||
David O'Toole wrote @samp{org-publish.el} and drafted the
|
||
manual chapter about publishing.
|
||
|
||
@item
|
||
Jambunathan K. contributed the ODT exporter.
|
||
|
||
@item
|
||
Sebastien Vauban reported many issues with @LaTeX{} and Beamer export
|
||
and enabled source code highlighting in Gnus.
|
||
|
||
@item
|
||
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.
|
||
|
||
@item
|
||
Jürgen Vollmer contributed code generating the table of contents in
|
||
HTML output.
|
||
|
||
@item
|
||
Samuel Wales has provided important feedback and bug reports.
|
||
|
||
@item
|
||
Chris Wallace provided a patch implementing the @samp{QUOTE} block.
|
||
|
||
@item
|
||
David Wainberg suggested archiving, and improvements to the
|
||
linking system.
|
||
|
||
@item
|
||
Carsten Wimmer suggested some changes and helped fix a bug in
|
||
linking to Gnus.
|
||
|
||
@item
|
||
Roland Winkler requested additional key bindings to make Org work on
|
||
a TTY.
|
||
|
||
@item
|
||
Piotr Zielinski wrote @samp{org-mouse.el}, proposed agenda
|
||
blocks and contributed various ideas and code snippets.
|
||
|
||
@item
|
||
Marco Wahl wrote @samp{org-eww.el}.
|
||
@end itemize
|
||
|
||
@node GNU Free Documentation License
|
||
@appendix GNU Free Documentation License
|
||
|
||
@include doclicense.texi
|
||
|
||
@node Main Index
|
||
@chapter Main Index
|
||
|
||
@printindex cp
|
||
|
||
@node Key Index
|
||
@chapter Key Index
|
||
|
||
@printindex ky
|
||
|
||
@node Command and Function Index
|
||
@chapter Command and Function Index
|
||
|
||
@printindex fn
|
||
|
||
@node Variable Index
|
||
@chapter 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
|
||
@kbd{M-x org-customize} and then click yourself through the tree.
|
||
|
||
@printindex vr
|
||
|
||
@bye |