diff --git a/org b/org index 1cea14b0b..d8899e210 100644 --- a/org +++ b/org @@ -5,7 +5,7 @@ START-INFO-DIR-ENTRY * Org Mode: (org). Outline-based notes management and organizer END-INFO-DIR-ENTRY - This manual is for Org-mode (version 4.79). + This manual is for Org-mode (version 5.01). Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation @@ -27,7 +27,7 @@ File: org, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) Org Mode Manual *************** -This manual is for Org-mode (version 4.79). +This manual is for Org-mode (version 5.01). Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation @@ -51,6 +51,7 @@ This manual is for Org-mode (version 4.79). * Hyperlinks:: Notes in context * TODO items:: Every tree branch can be a TODO item * Tags:: Tagging headlines and matching sets of tags +* Properties:: * Timestamps:: Assign date and time to items * Agenda views:: Collecting information into views * Embedded LaTeX:: LaTeX fragments and formulas @@ -81,6 +82,7 @@ Document Structure * Archiving:: Move done task trees to a different place * Sparse trees:: Matches embedded in context * Plain lists:: Additional structure within an entry +* Drawers:: Archiving @@ -148,6 +150,19 @@ Tags * Setting tags:: How to assign tags to a headline * Tag searches:: Searching for combinations of tags +Properties + +* Property syntax:: How properties are spelled out +* Special properties:: Access to other Org-mode features +* Property searches:: Matching property values +* Column view:: Tabular viewing and editing +* Property API:: Properties for Lisp programmers + +Column View + +* Defining columns:: The COLUMNS format property +* Using column view:: How to create and use column view + Timestamps * Time stamps:: Assigning a time to a tree entry @@ -184,7 +199,7 @@ The built-in agenda views * Weekly/Daily agenda:: The calendar page with current tasks * Global TODO list:: All unfinished action items -* Matching headline tags:: Structured information with fine-tuned search +* Matching tags and properties:: Structured information with fine-tuned search * Timeline:: Time-sorted view for single file * Stuck projects:: Find projects you need to review @@ -277,6 +292,7 @@ Extensions, Hooks and Hacking * Tables in arbitrary syntax:: Orgtbl for LaTeX and other programs * Dynamic blocks:: Automatically filled blocks * Special agenda views:: Customized views +* Using the property API:: Writing programs that use entry properties Tables in arbitrary syntax @@ -303,7 +319,7 @@ File: org, Node: Summary, Next: Installation, Prev: Introduction, Up: Introd 1.1 Summary =========== -Org-mode is a mode for keeping notes, maintaining ToDo lists, and doing +Org-mode is a mode for keeping notes, maintaining TODO lists, and doing project planning with a fast and effective plain-text system. Org-mode develops organizational tasks around NOTES files that @@ -311,7 +327,7 @@ contain lists or information about projects as plain text. Org-mode 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. Org-mode supports ToDo items, deadlines, +with a built-in table editor. Org-mode supports TODO items, deadlines, time stamps, and scheduling. It dynamically compiles entries into an agenda that utilizes and smoothly integrates much of the Emacs calendar and diary. Plain text URL-like links connect to websites, emails, @@ -496,6 +512,7 @@ edit the structure of the document. * Archiving:: Move done task trees to a different place * Sparse trees:: Matches embedded in context * Plain lists:: Additional structure within an entry +* Drawers::  File: org, Node: Outlines, Next: Headlines, Prev: Document structure, Up: Document structure @@ -871,7 +888,7 @@ control on how much context is shown around each match. display for outlining, not text properties.  -File: org, Node: Plain lists, Prev: Sparse trees, Up: Document structure +File: org, Node: Plain lists, Next: Drawers, Prev: Sparse trees, Up: Document structure 2.8 Plain lists =============== @@ -890,9 +907,9 @@ left-aligned with the other numbers in the list. Indentation also determines the end of a list item. It ends before the next line that is indented like the bullet/number, or less. Empty lines are part of the previous item, so you can have several paragraphs in one item. If -you would like an emtpy line to terminate all currently open plain +you would like an empty line to terminate all currently open plain lists, configure the variable `org-empty-line-terminates-plain-lists'. -Here is an for example: +Here is an example: ** Lord of the Rings My favorite scenes are (in this order) @@ -958,7 +975,12 @@ line of an item (the line with the bullet or number). toggle the state of the checkbox. If not, make this command makes sure that all the items on this list level use the same bullet. Furthermore, if this is an ordered list, make sure the numbering - is ok. + is ok. + +`C-c -' + Cycle the entire list level through the different itemize/enumerate + bullets (`-', `+', `*', `1.', `1)'). With prefix arg, select the + nth bullet from this list. ---------- Footnotes ---------- @@ -973,6 +995,30 @@ list items. XEmacs, you should use Kyle E. Jones' `filladapt.el'. To turn this on, put into `.emacs': `(require 'filladapt)' + +File: org, Node: Drawers, Prev: Plain lists, Up: Document structure + +2.9 Drawers +=========== + +Sometimes you want to keep information associated with an entry, but you +normally don't want to see it, except when explicitly asking for it. +For this, Org-mode has _drawers_. Drawers need to be configured with +the variable `org-drawers', and look like this: + + ** This is a headline + Still outside the drawer + :DRAWERNAME: + This is inside the drawer. + :END: + After the drawer. + + Visibility cycling (*note Visibility cycling::) on the headline will +hide and show 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 there. Org-mode uses a drawer for storing +properties (*note Properties::). +  File: org, Node: Tables, Next: Hyperlinks, Prev: Document structure, Up: Top @@ -1390,13 +1436,20 @@ Named references `$name' is interpreted as the name of a column, parameter or constant. Constants are defined globally through the variable -`org-table-formula-constants'. If you have the `constants.el' package, -it will also be used to resolve constants, including natural constants -like `$h' for Planck's constant, and units like `$km' for -kilometers(1). Column names and parameters can be specified in special -table lines. These are described below, see *Note Advanced features::. -All names must start with a letter, and further consist of letters and -numbers. +`org-table-formula-constants', and locally (for the file) through a +line like + + #+CONSTANTS: c=299792458. pi=3.14 eps=2.4e-6 + +Also properties (*note Properties::) can be used as constants in table +formulas: For a property `:XYZ:' use the name `$PROP_XYZ', and the +property will be searched in the current outline entry and in the +hierarchy above it. If you have the `constants.el' package, it will +also be used to resolve constants, including natural constants like +`$h' for Planck's constant, and units like `$km' for kilometers(1). +Column names and parameters can be specified in special table lines. +These are described below, see *Note Advanced features::. All names +must start with a letter, and further consist of letters and numbers. ---------- Footnotes ---------- @@ -2259,6 +2312,8 @@ insertion of content: %a annotation, normally the link created with `org-store-link' %i initial content, the region when remember is called with C-u. The entire text will be indented like `%i' itself. + %^g prompt for tags, with completion on tags in target file. + %^G prompt for tags, with completion all tags in all agenda files. %:keyword specific information for certain link types, see below For specific link types, the following keywords will be defined: @@ -2398,7 +2453,10 @@ The most important commands to work with TODO entries are: buffer is in `agenda-mode', so there are commands to examine and manipulate the TODO entries directly from that buffer (*note Agenda commands::). *Note Global TODO list::, for more - information. + information. + +`S-M-' + Insert a new TODO entry below the current one.  File: org, Node: TODO extensions, Next: Priorities, Prev: TODO basics, Up: TODO items @@ -2685,7 +2743,7 @@ The following commands work with checkboxes: with `C-c C-c'.  -File: org, Node: Tags, Next: Timestamps, Prev: TODO items, Up: Top +File: org, Node: Tags, Next: Properties, Prev: TODO items, Up: Top 6 Tags ****** @@ -2866,7 +2924,7 @@ information into special lists. `C-c a m' Create a global list of tag matches from all agenda files. *Note - Matching headline tags::. + Matching tags and properties::. `C-c a M' Create a global list of tag matches from all agenda files, but @@ -2924,9 +2982,218 @@ instead of any TAG an expression like `LEVEL=3'. For example, a search BOSS and are _not_ marked with the todo keyword DONE.  -File: org, Node: Timestamps, Next: Agenda views, Prev: Tags, Up: Top +File: org, Node: Properties, Next: Timestamps, Prev: Tags, Up: Top -7 Timestamps +7 Properties +************ + +Properties are a set of key-value pairs associated with an entry. There +are two main applications for properties in Org-mode. First, properties +are like tags, but with a value. For example, in a file where you +document bugs and plan releases of a piece of software, instead of using +tags like `:release_1:', `:release_2:', it can be more efficient to use +a property `RELEASE' with a value `1.0' or `2.0'. Second, you can use +properties to implement (very basic) database capabilities in an +Org-mode buffer, for example to create a list of Music CD's you own. + +* Menu: + +* Property syntax:: How properties are spelled out +* Special properties:: Access to other Org-mode features +* Property searches:: Matching property values +* Column view:: Tabular viewing and editing +* Property API:: Properties for Lisp programmers + + +File: org, Node: Property syntax, Next: Special properties, Prev: Properties, Up: Properties + +7.1 Property Syntax +=================== + +Properties are key-value pairs. They need to be inserted into a special +drawer (*note Drawers::) with the name `PROPERTIES'. Each property is +specified on a single line, with the key (surrounded by colons) first, +and the value after it. Here is an example: + + * CD collection + ** Classic + *** Goldberg Variations + :PROPERTIES: + :Title: Goldberg Variations + :Composer: J.S. Bach + :Artist: Glen Gould + :END: + +The following commands help to insert properties: + +`M-' + After an initial colon in a line, complete property keys. All + keys used in the current file will be offered as possible + completions. + + +File: org, Node: Special properties, Next: Property searches, Prev: Property syntax, Up: Properties + +7.2 Special Properties +====================== + +Several properties are special, because they can be used to access other +features of Org-mode like the TODO status: + + TODO The TODO keyword of the entry. + TAGS The tags defined directly in the headline. + ALLTAGS All tags, including inherited ones. + PRIORITY The priority of the entry, a string with a single letter. + DEADLINE The deadline time string, without the angular brackets. + SCHEDULED The scheduling time stamp, without the angular brackets. + + +File: org, Node: Property searches, Next: Column view, Prev: Special properties, Up: Properties + +7.3 Property searches +===================== + +To create sparse trees and special lists with selection based on +properties, the same commands are used as for tag searches (*note Tag +searches::), and the same logic applies. For example, a search string + + +WORK-BOSS+PRIORITY="A"+coffee="unlimited"+with={Sarah\|Denny} + +finds entries tagged `:WORK:' but not `:BOSS:', which also have a +priority value `A', a `:coffee:' property with the value `unlimited', +and a `:with:' property that is matched by the regular expression +`Sarah\|Denny'. + + +File: org, Node: Column view, Next: Property API, Prev: Property searches, Up: Properties + +7.4 Column View +=============== + +If different items in a document have similar properties, it can be nice +to view and edit those properties in a table-like format, in _column +view_. Org-mode implements columns by overlaying a tabular structure +over the headline of an item. So the column view does not use a +special buffer, it happens in exactly the same buffer where the outline +is, and only temporarily changes the look of this buffer - not the +content. This has the advantage that you can still change the +visibility of the outline tree. For example, you get a compact table by +switching to CONTENTS view, 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 (*note Agenda +views::) where queries have collected selected items, possibly from a +number of files. + +* Menu: + +* Defining columns:: The COLUMNS format property +* Using column view:: How to create and use column view + + +File: org, Node: Defining columns, Next: Using column view, Prev: Column view, Up: Column view + +7.4.1 Defining Columns +---------------------- + +Setting up a column view first requires defining the columns. A column +definition is a property itself and looks like this: + + :COLUMNS: %25ITEM %TAGS %PRIORITY %TODO + + This definition means that column 1 should be the first 25 +characters of the item itself, i.e. of the headline. You probably +always should start the column definition with the ITEM specifier - +just select a useful width for it. The other specifiers create columns +for the local tags, for the priority and for the TODO state. When no +width is given after the `%' character, the column will be exactly as +wide as it need to be in order to fully display all values. + + If a `COLUMNS' property is present in an entry, it defines columns +for the entry itself, and for the entire subtree below it. Since the +column definition is part of the hierarchical structure of the +document, you can define columns on level 1 that are general enough for +all sublevels, and more specific columns further down, when you edit a +deeper part of the tree. Here is an example: + + * People + :PROPERTIES: + :COLUMNS: %25ITEM %Name + :END: + ** Family + :PROPERTIES: + :COLUMNS: %25ITEM %Name %3Age + :END: + *** Sam + Info about Sam, including a property list with Name and Age. + *** Sarah + Info about Sarah, including a property list with Name and Age. + ** Office + :PROPERTIES: + :COLUMNS: %25ITEM %Name %Function %Salary + :END: + *** Boss + Info about the Boss, including a property list with Name, + Function and Salary (if only we knew....). + + Now we have defined three different sets of columns. If you switch +to column view in the _Family_ section, you will get a different table +than if you do it in the _Office_ section. However, if you switch to +column view with the cursor on the _People_ section, the table will +cover all entries, but contain only the _Name_ column. + + If no COLUMNS property applies to a given location, Org-mode uses a +default format specified in the variable `org-default-columns-format'. +This format in particular also applies when column view is invoked with +the cursor before the first headline. You can set the default format +on a per-file basis with a line (don't forget to press `C-c C-c' to +activate any changes to this line). + + #+COLUMNS: %25ITEM ....." + + +File: org, Node: Using column view, Prev: Defining columns, Up: Column view + +7.4.2 Using Column View +----------------------- + +`C-c C-x C-c' + Create the column view for the local environment. This command + searches the hierarchy, up from point, for a `COLUMNS' property + that defines a format. When one is found, the column view table + is established for the entire subtree. + +` ' + Move through the column view from field to field. + +`e' + Edit the property at point. For the special properties, this will + invoke the same interface that you normally use to change that + property. For example, when editing a TAGS property, the tag + completion or fast selection interface will pop up. + +`v' + View the full value of this property. This is useful if the width + of the column is smaller than that of the value. + +`q' + Exit column view. + + +File: org, Node: Property API, Prev: Column view, Up: Properties + +7.5 The Property API +==================== + +There is a full API for accessing and changing properties. This API can +be used by Emacs Lisp programs to work with properties and to implement +features based on them. For more information see *Note Using the +property API::. + + +File: org, Node: Timestamps, Next: Agenda views, Prev: Properties, Up: Top + +8 Timestamps ************ Items can be labeled with timestamps to make them useful for project @@ -2942,7 +3209,7 @@ planning.  File: org, Node: Time stamps, Next: Creating timestamps, Prev: Timestamps, Up: Timestamps -7.1 Time stamps, deadlines and scheduling +8.1 Time stamps, deadlines and scheduling ========================================= A time stamp is a specification of a date (possibly with time or a range @@ -3004,7 +3271,7 @@ used to these, see *Note Custom time format::  File: org, Node: Creating timestamps, Next: Deadlines and scheduling, Prev: Time stamps, Up: Timestamps -7.2 Creating timestamps +8.2 Creating timestamps ======================= For Org-mode to recognize time stamps, they need to be in the specific @@ -3064,7 +3331,7 @@ format.  File: org, Node: The date/time prompt, Next: Custom time format, Prev: Creating timestamps, Up: Creating timestamps -7.2.1 The date/time prompt +8.2.1 The date/time prompt -------------------------- When Org-mode prompts for a date/time, the prompt suggests to enter an @@ -3132,7 +3399,7 @@ the calendar fully from the minibuffer:  File: org, Node: Custom time format, Prev: The date/time prompt, Up: Creating timestamps -7.2.2 Custom time format +8.2.2 Custom time format ------------------------ Org-mode uses the standard ISO notation for dates and times as it is @@ -3171,7 +3438,7 @@ consequences:  File: org, Node: Deadlines and scheduling, Next: Progress logging, Prev: Creating timestamps, Up: Timestamps -7.3 Deadlines and Scheduling +8.3 Deadlines and Scheduling ============================ A time stamp may be preceded by special keywords to facilitate planning @@ -3213,7 +3480,7 @@ DONE. If you don't like this, set the variable  File: org, Node: Inserting deadline/schedule, Next: Repeated tasks, Prev: Deadlines and scheduling, Up: Deadlines and scheduling -7.3.1 Inserting deadline/schedule +8.3.1 Inserting deadline/schedule --------------------------------- The following commands allow to quickly insert a deadline or to schedule @@ -3238,7 +3505,7 @@ an item:  File: org, Node: Repeated tasks, Prev: Inserting deadline/schedule, Up: Deadlines and scheduling -7.3.2 Repeated Tasks +8.3.2 Repeated Tasks -------------------- Some tasks need to be repeated again and again, and Org-mode therefore @@ -3276,7 +3543,7 @@ task - just make sure that the repeater intervals on both are the same.  File: org, Node: Progress logging, Prev: Deadlines and scheduling, Up: Timestamps -7.4 Progress Logging +8.4 Progress Logging ==================== Org-mode can automatically record a time stamp when you mark a TODO item @@ -3294,7 +3561,7 @@ on an aspect of a project.  File: org, Node: Closing items, Next: Tracking TODO state changes, Prev: Progress logging, Up: Progress logging -7.4.1 Closing items +8.4.1 Closing items ------------------- If you want to keep track of _when_ a certain TODO item was finished, @@ -3323,7 +3590,7 @@ the timestamp, use(2)  File: org, Node: Tracking TODO state changes, Next: Clocking work time, Prev: Closing items, Up: Progress logging -7.4.2 Tracking TODO state changes +8.4.2 Tracking TODO state changes --------------------------------- When TODO keywords are used as workflow states (*note Workflow @@ -3345,7 +3612,7 @@ these into a separate file that starts with:  File: org, Node: Clocking work time, Prev: Tracking TODO state changes, Up: Progress logging -7.4.3 Clocking work time +8.4.3 Clocking work time ------------------------ Org-mode allows you to clock the time you spent on specific tasks in a @@ -3432,7 +3699,7 @@ the line is broken here only to fit it onto the manual.  File: org, Node: Agenda views, Next: Embedded LaTeX, Prev: Timestamps, Up: Top -8 Agenda Views +9 Agenda Views ************** Due to the way Org-mode works, TODO items, time-stamped items, and @@ -3482,7 +3749,7 @@ the window configuration is restored when the agenda exits:  File: org, Node: Agenda files, Next: Agenda dispatcher, Prev: Agenda views, Up: Agenda views -8.1 Agenda files +9.1 Agenda files ================ The information to be shown is collected from all _agenda files_, the @@ -3519,7 +3786,7 @@ command will actually limit the command to the current file, and ignore  File: org, Node: Agenda dispatcher, Next: Built-in agenda views, Prev: Agenda files, Up: Agenda views -8.2 The agenda dispatcher +9.2 The agenda dispatcher ========================= The views are created through a dispatcher that should be bound to a @@ -3536,7 +3803,7 @@ command. The dispatcher offers the following default commands: `m / M' Create a list of headlines matching a TAGS expression (*note - Matching headline tags::). + Matching tags and properties::). `L' Create the timeline view for the current buffer (*note Timeline::). @@ -3563,7 +3830,7 @@ a number of special tags matches. *Note Custom agenda views::.  File: org, Node: Built-in agenda views, Next: Presentation and sorting, Prev: Agenda dispatcher, Up: Agenda views -8.3 The built-in agenda views +9.3 The built-in agenda views ============================= In this section we describe the built-in views. @@ -3572,14 +3839,14 @@ In this section we describe the built-in views. * Weekly/Daily agenda:: The calendar page with current tasks * Global TODO list:: All unfinished action items -* Matching headline tags:: Structured information with fine-tuned search +* Matching tags and properties:: Structured information with fine-tuned search * Timeline:: Time-sorted view for single file * Stuck projects:: Find projects you need to review  File: org, Node: Weekly/Daily agenda, Next: Global TODO list, Prev: Built-in agenda views, Up: Built-in agenda views -8.3.1 The weekly/daily agenda +9.3.1 The weekly/daily agenda ----------------------------- The purpose of the weekly/daily _agenda_ is to act like a page of a @@ -3636,13 +3903,13 @@ will be made in the agenda: #+CATEGORY: Holiday %%(org-calendar-holiday) ; special function for holiday names #+CATEGORY: Ann - %%(diary-anniversary 14 5 1956) Artur Dent %d is years old + %%(diary-anniversary 14 5 1956) Arthur Dent is %d years old %%(diary-anniversary 2 10 1869) Mahatma Gandhi would be %d years old  -File: org, Node: Global TODO list, Next: Matching headline tags, Prev: Weekly/Daily agenda, Up: Built-in agenda views +File: org, Node: Global TODO list, Next: Matching tags and properties, Prev: Weekly/Daily agenda, Up: Built-in agenda views -8.3.2 The global TODO list +9.3.2 The global TODO list -------------------------- The global TODO list contains all unfinished TODO items, formatted and @@ -3687,10 +3954,10 @@ it more compact: the variable `org-agenda-todo-list-sublevels' to get this behavior.  -File: org, Node: Matching headline tags, Next: Timeline, Prev: Global TODO list, Up: Built-in agenda views +File: org, Node: Matching tags and properties, Next: Timeline, Prev: Global TODO list, Up: Built-in agenda views -8.3.3 Matching headline tags ----------------------------- +9.3.3 Matching Tags and Properties +---------------------------------- If headlines in the agenda files are marked with _tags_ (*note Tags::), you can select headlines based on the tags that apply to them and @@ -3714,9 +3981,9 @@ collect them into an agenda buffer. Agenda commands::.  -File: org, Node: Timeline, Next: Stuck projects, Prev: Matching headline tags, Up: Built-in agenda views +File: org, Node: Timeline, Next: Stuck projects, Prev: Matching tags and properties, Up: Built-in agenda views -8.3.4 Timeline for a single file +9.3.4 Timeline for a single file -------------------------------- The timeline summarizes all time-stamped items from a single Org-mode @@ -3734,7 +4001,7 @@ Agenda commands::.  File: org, Node: Stuck projects, Prev: Timeline, Up: Built-in agenda views -8.3.5 Stuck projects +9.3.5 Stuck projects -------------------- If you are following a system like David Allen's GTD to organize your @@ -3775,7 +4042,7 @@ not stuck. The correct customization for this is  File: org, Node: Presentation and sorting, Next: Agenda commands, Prev: Built-in agenda views, Up: Agenda views -8.4 Presentation and sorting +9.4 Presentation and sorting ============================ Before displaying items in an agenda view, Org-mode visually prepares @@ -3795,7 +4062,7 @@ associated with the item.  File: org, Node: Categories, Next: Time-of-day specifications, Prev: Presentation and sorting, Up: Presentation and sorting -8.4.1 Categories +9.4.1 Categories ---------------- The category is a broad label assigned to each agenda item. By default, @@ -3812,7 +4079,7 @@ buffer looks best if the category is not longer than 10 characters.  File: org, Node: Time-of-day specifications, Next: Sorting of agenda items, Prev: Categories, Up: Presentation and sorting -8.4.2 Time-of-Day Specifications +9.4.2 Time-of-Day Specifications -------------------------------- Org-mode checks each agenda item for a time-of-day specification. The @@ -3857,7 +4124,7 @@ timed entries are embedded in a time grid, like  File: org, Node: Sorting of agenda items, Prev: Time-of-day specifications, Up: Presentation and sorting -8.4.3 Sorting of agenda items +9.4.3 Sorting of agenda items ----------------------------- Before being inserted into a view, the items are sorted. How this is @@ -3885,7 +4152,7 @@ done depends on the type of view.  File: org, Node: Agenda commands, Next: Custom agenda views, Prev: Presentation and sorting, Up: Agenda views -8.5 Commands in the agenda buffer +9.5 Commands in the agenda buffer ================================= Entries in the agenda buffer are linked back to the org file or diary @@ -3950,11 +4217,8 @@ Change display `o' Delete other windows. -`w' - Switch to weekly view (7 days displayed together). - -`d' - Switch to daily view (just one day displayed). +`d w m y' + Switch to day/week/month/year view. `D' Toggle the inclusion of diary entries. See *Note Weekly/Daily @@ -4131,7 +4395,7 @@ Quit and Exit  File: org, Node: Custom agenda views, Prev: Agenda commands, Up: Agenda views -8.6 Custom agenda views +9.6 Custom agenda views ======================= Custom agenda commands serve two purposes: to store and quickly access @@ -4150,7 +4414,7 @@ dispatcher (*note Agenda dispatcher::), just like the default commands.  File: org, Node: Storing searches, Next: Block agenda, Prev: Custom agenda views, Up: Custom agenda views -8.6.1 Storing searches +9.6.1 Storing searches ---------------------- The first application of custom searches is the definition of keyboard @@ -4203,7 +4467,7 @@ example above will therefore define:  File: org, Node: Block agenda, Next: Setting Options, Prev: Storing searches, Up: Custom agenda views -8.6.2 Block agenda +9.6.2 Block agenda ------------------ Another possibility is the construction of agenda views that comprise @@ -4233,7 +4497,7 @@ your agenda for the current week, all TODO items that carry the tag  File: org, Node: Setting Options, Next: Exporting Agenda Views, Prev: Block agenda, Up: Custom agenda views -8.6.3 Setting Options for custom commands +9.6.3 Setting Options for custom commands ----------------------------------------- Org-mode contains a number of variables regulating agenda construction @@ -4291,7 +4555,7 @@ yourself.  File: org, Node: Exporting Agenda Views, Next: Extracting Agenda Information for other programs, Prev: Setting Options, Up: Custom agenda views -8.6.4 Exporting Agenda Views +9.6.4 Exporting Agenda Views ---------------------------- If you are away from your computer, it can be very useful to have a @@ -4393,7 +4657,7 @@ them in order to be able to specify filenames.  File: org, Node: Extracting Agenda Information for other programs, Prev: Exporting Agenda Views, Up: Custom agenda views -8.6.5 Extracting Agenda Information for other programs +9.6.5 Extracting Agenda Information for other programs ------------------------------------------------------ Org-mode provides commands to access agenda information for the command @@ -4485,8 +4749,8 @@ Emacs/org-mode and prints all the items, preceded by a checkbox:  File: org, Node: Embedded LaTeX, Next: Exporting, Prev: Agenda views, Up: Top -9 Embedded LaTeX -**************** +10 Embedded LaTeX +***************** Plain ASCII is normally sufficient for almost all note taking. One exception, however, are scientific notes which need to be able to @@ -4517,8 +4781,8 @@ for simplicity I am blurring this distinction.  File: org, Node: Math symbols, Next: Subscripts and Superscripts, Prev: Embedded LaTeX, Up: Embedded LaTeX -9.1 Math symbols -================ +10.1 Math symbols +================= You can use LaTeX macros to insert special symbols like `\alpha' to indicate the Greek letter, or `\to' to indicate an arrow. Completion @@ -4536,8 +4800,8 @@ is `α' and `→', respectively.  File: org, Node: Subscripts and Superscripts, Next: LaTeX fragments, Prev: Math symbols, Up: Embedded LaTeX -9.2 Subscripts and Superscripts -=============================== +10.2 Subscripts and Superscripts +================================ Just like in LaTeX, `^' and `_' are used to indicate super- and subscripts. Again, these can be used without embedding them in @@ -4557,8 +4821,8 @@ are surrounded with `' and `' tags, respectively.  File: org, Node: LaTeX fragments, Next: Processing LaTeX fragments, Prev: Subscripts and Superscripts, Up: Embedded LaTeX -9.3 LaTeX fragments -=================== +10.3 LaTeX fragments +==================== With symbols, sub- and superscripts, HTML is pretty much at its end when it comes to representing mathematical formulas(1). More complex @@ -4610,8 +4874,8 @@ converting formulas into images seems the way to go.  File: org, Node: Processing LaTeX fragments, Next: CDLaTeX mode, Prev: LaTeX fragments, Up: Embedded LaTeX -9.4 Processing LaTeX fragments -============================== +10.4 Processing LaTeX fragments +=============================== LaTeX fragments can be processed to produce a preview images of the typeset expressions: @@ -4636,8 +4900,8 @@ setting is active:  File: org, Node: CDLaTeX mode, Prev: Processing LaTeX fragments, Up: Embedded LaTeX -9.5 Using CDLaTeX to enter math -=============================== +10.5 Using CDLaTeX to enter math +================================ CDLaTeX-mode is a minor mode that is normally used in combination with a major LaTeX mode like AUCTeX in order to speed-up insertion of @@ -4691,7 +4955,7 @@ fragment, see the documentation of the function  File: org, Node: Exporting, Next: Publishing, Prev: Embedded LaTeX, Up: Top -10 Exporting +11 Exporting ************ Org-mode documents can be exported into a variety of other formats. For @@ -4723,7 +4987,7 @@ output produced. *Note Text interpretation::, for more details.  File: org, Node: ASCII export, Next: HTML export, Prev: Exporting, Up: Exporting -10.1 ASCII export +11.1 ASCII export ================= ASCII export produces a simple and very readable version of an Org-mode @@ -4757,7 +5021,7 @@ indentation than the first, these are left alone.  File: org, Node: HTML export, Next: XOXO export, Prev: ASCII export, Up: Exporting -10.2 HTML export +11.2 HTML export ================ Org-mode contains an HTML (XHTML 1.0 strict) exporter with extensive @@ -4775,7 +5039,7 @@ but with additional support for tables.  File: org, Node: Export commands, Next: Quoting HTML tags, Prev: HTML export, Up: HTML export -10.2.1 HTML export commands +11.2.1 HTML export commands --------------------------- `C-c C-e h' @@ -4819,7 +5083,7 @@ creates two levels of headings and does the rest as items.  File: org, Node: Quoting HTML tags, Next: Links, Prev: Export commands, Up: HTML export -10.2.2 Quoting HTML tags +11.2.2 Quoting HTML tags ------------------------ Plain `<' and `>' are always transformed to `<' and `>' in HTML @@ -4839,7 +5103,7 @@ or  File: org, Node: Links, Next: Images, Prev: Quoting HTML tags, Up: HTML export -10.2.3 Links +11.2.3 Links ------------ Internal links (*note Internal links::) will continue to work in HTML @@ -4855,7 +5119,7 @@ Publishing links::.  File: org, Node: Images, Next: CSS support, Prev: Links, Up: HTML export -10.2.4 Images +11.2.4 Images ------------- HTML export can inline images given as links in the Org-mode file, and @@ -4880,7 +5144,7 @@ and you could use `http' addresses just as well.  File: org, Node: CSS support, Prev: Images, Up: HTML export -10.2.5 CSS support +11.2.5 CSS support ------------------ You can also give style information for the exported file. The HTML @@ -4920,7 +5184,7 @@ should have no `#' at the start of the line.  File: org, Node: XOXO export, Next: iCalendar export, Prev: HTML export, Up: Exporting -10.3 XOXO export +11.3 XOXO export ================ Org-mode contains an exporter that produces XOXO-style output. @@ -4936,7 +5200,7 @@ does not interpret any additional Org-mode features.  File: org, Node: iCalendar export, Next: Text interpretation, Prev: XOXO export, Up: Exporting -10.4 iCalendar export +11.4 iCalendar export ===================== Some people like to use Org-mode for keeping track of projects, but @@ -4967,7 +5231,7 @@ application you are using. The FAQ covers this issue.  File: org, Node: Text interpretation, Prev: iCalendar export, Up: Exporting -10.5 Text interpretation by the exporter +11.5 Text interpretation by the exporter ======================================== The exporter backends interpret additional structure in the Org-mode @@ -4984,7 +5248,7 @@ file in order to produce better output.  File: org, Node: Comment lines, Next: Initial text, Prev: Text interpretation, Up: Text interpretation -10.5.1 Comment lines +11.5.1 Comment lines -------------------- Lines starting with `#' in column zero are treated as comments and will @@ -4997,7 +5261,7 @@ never be exported. Also entire subtrees starting with the word  File: org, Node: Initial text, Next: Footnotes, Prev: Comment lines, Up: Text interpretation -10.5.2 Text before the first headline +11.5.2 Text before the first headline ------------------------------------- Org-mode normally ignores any text before the first headline when @@ -5033,7 +5297,7 @@ headline when exporting the file, you can use the `#+TEXT' construct:  File: org, Node: Footnotes, Next: Enhancing text, Prev: Initial text, Up: Text interpretation -10.5.3 Footnotes +11.5.3 Footnotes ---------------- Numbers in square brackets are treated as footnotes, so that you can use @@ -5054,7 +5318,7 @@ binding, you could use `org-replace-disputed-keys' and  File: org, Node: Enhancing text, Next: Export options, Prev: Footnotes, Up: Text interpretation -10.5.4 Enhancing text for export +11.5.4 Enhancing text for export -------------------------------- Some of the export backends of Org-mode allow for sophisticated text @@ -5102,7 +5366,7 @@ should never be used.  File: org, Node: Export options, Prev: Enhancing text, Up: Text interpretation -10.5.5 Export options +11.5.5 Export options --------------------- The exporter recognizes special lines in the buffer which provide @@ -5144,7 +5408,7 @@ you can:  File: org, Node: Publishing, Next: Miscellaneous, Prev: Exporting, Up: Top -11 Publishing +12 Publishing ************* Org-mode includes(1) a publishing management system that allows you to @@ -5172,7 +5436,7 @@ separately. Also make sure org.el is at least version 4.27.  File: org, Node: Configuration, Next: Sample configuration, Prev: Publishing, Up: Publishing -11.1 Configuration +12.1 Configuration ================== Publishing needs significant configuration to specify files, destination @@ -5191,7 +5455,7 @@ and many other properties of a project.  File: org, Node: Project alist, Next: Sources and destinations, Prev: Configuration, Up: Configuration -11.1.1 The variable `org-publish-project-alist' +12.1.1 The variable `org-publish-project-alist' ----------------------------------------------- Org-publish is configured almost entirely through setting the value of @@ -5216,7 +5480,7 @@ you publish such a "meta-project" all the components will also publish.  File: org, Node: Sources and destinations, Next: Selecting files, Prev: Project alist, Up: Configuration -11.1.2 Sources and destinations for files +12.1.2 Sources and destinations for files ----------------------------------------- Most properties are optional, but some should always be set. In @@ -5233,7 +5497,7 @@ and where to put published files.  File: org, Node: Selecting files, Next: Publishing action, Prev: Sources and destinations, Up: Configuration -11.1.3 Selecting files +12.1.3 Selecting files ---------------------- By default, all files with extension `.org' in the base directory are @@ -5250,7 +5514,7 @@ properties  File: org, Node: Publishing action, Next: Publishing options, Prev: Selecting files, Up: Configuration -11.1.4 Publishing Action +12.1.4 Publishing Action ------------------------ Publishing means that a file is copied to the destination directory and @@ -5276,7 +5540,7 @@ provides one for attachments (files that only need to be copied):  File: org, Node: Publishing options, Next: Publishing links, Prev: Publishing action, Up: Configuration -11.1.5 Options for the HTML exporter +12.1.5 Options for the HTML exporter ------------------------------------ The property list can be used to set many export options for the HTML @@ -5322,7 +5586,7 @@ however, override everything.  File: org, Node: Publishing links, Next: Project page index, Prev: Publishing options, Up: Configuration -11.1.6 Links between published files +12.1.6 Links between published files ------------------------------------ To create a link from one Org-mode file to another, you would use @@ -5354,7 +5618,7 @@ is part of any project in `org-publish-project-alist'.  File: org, Node: Project page index, Prev: Publishing links, Up: Configuration -11.1.7 Project page index +12.1.7 Project page index ------------------------- The following properties may be used to control publishing of an index @@ -5372,7 +5636,7 @@ of files or summary page for a given project.  File: org, Node: Sample configuration, Next: Triggering publication, Prev: Configuration, Up: Publishing -11.2 Sample configuration +12.2 Sample configuration ========================= Below we provide two example configurations. The first one is a simple @@ -5387,7 +5651,7 @@ more complex, with a multi-component project.  File: org, Node: Simple example, Next: Complex example, Prev: Sample configuration, Up: Sample configuration -11.2.1 Example: simple publishing configuration +12.2.1 Example: simple publishing configuration ----------------------------------------------- This example publishes a set of Org-mode files to the `public_html' @@ -5406,7 +5670,7 @@ directory on the local machine.  File: org, Node: Complex example, Prev: Simple example, Up: Sample configuration -11.2.2 Example: complex publishing configuration +12.2.2 Example: complex publishing configuration ------------------------------------------------ This more complicated example publishes an entire website, including @@ -5454,7 +5718,7 @@ right place on the webserver, and publishing images to it.  File: org, Node: Triggering publication, Prev: Sample configuration, Up: Publishing -11.3 Triggering publication +12.3 Triggering publication =========================== Once org-publish is properly configured, you can publish with the @@ -5480,7 +5744,7 @@ force publishing of all files by giving a prefix argument.  File: org, Node: Miscellaneous, Next: Extensions and Hacking, Prev: Publishing, Up: Top -12 Miscellaneous +13 Miscellaneous **************** * Menu: @@ -5497,7 +5761,7 @@ File: org, Node: Miscellaneous, Next: Extensions and Hacking, Prev: Publishin  File: org, Node: Completion, Next: Customization, Prev: Miscellaneous, Up: Miscellaneous -12.1 Completion +13.1 Completion =============== Org-mode supports in-buffer completion. This type of completion does @@ -5514,10 +5778,15 @@ buffer and use the key to complete text right there. they can be used in search links like `[[*find this headline]]'. - * After `:', complete tags. The list of tags is taken from the - variable `org-tag-alist' (possibly set through the `#+TAGS' - in-buffer option, *note Setting tags::), or it is created - dynamically from all tags used in the current buffer. + * After `:' in a headline, complete tags. The list of tags is + taken from the variable `org-tag-alist' (possibly set through + the `#+TAGS' in-buffer option, *note Setting tags::), or it + is created dynamically from all tags used in the current + buffer. + + * After `:' and not in a headline, complete property keys. The + list of keys is constructed dynamically from all keys used in + the current buffer. * After `[', complete link abbreviations (*note Link abbreviations::). @@ -5535,7 +5804,7 @@ buffer and use the key to complete text right there.  File: org, Node: Customization, Next: In-buffer settings, Prev: Completion, Up: Miscellaneous -12.2 Customization +13.2 Customization ================== There are more than 180 variables that can be used to customize @@ -5549,7 +5818,7 @@ activated on a per-file basis, by putting special lines into the buffer  File: org, Node: In-buffer settings, Next: The very busy C-c C-c key, Prev: Customization, Up: Miscellaneous -12.3 Summary of in-buffer settings +13.3 Summary of in-buffer settings ================================== Org-mode uses special lines in the buffer to define settings on a @@ -5562,6 +5831,40 @@ press `C-c C-c' with the cursor still in the line to activate the changes immediately. Otherwise they become effective only when the file is visited again in a new Emacs session. +`#+ARCHIVE: %s_done::' + This line sets the archive location for the agenda file. It + applies for all subsequent lines until the next `#+CATEGORY' line, + or the end of the file. The first such line also applies to any + entries before it. The corresponding variable is + `org-archive-location'. + +`#+CATEGORY:' + This line sets the category for the agenda file. The category + applies for all subsequent lines until the next `#+CATEGORY' line, + or the end of the file. The first such line also applies to any + entries before it. + +`#+COLUMNS: %25ITEM .....' + Set the default format for columns view. This format applies when + columns view is invoked in location where no COLUMNS property + applies. + +`#+CONSTANTS: name1=value1 ...' + Set file-local values for constants to be used in table formulas. + This line set the local variable + `org-table-formula-constants-local'. The global version of theis + variable is `org-table-formula-constants'. corresponding + +`#+LINK: linkword replace' + These lines (several are allowed) specify link abbreviations. + *Note Link abbreviations::. The corresponding variable is + `org-link-abbrev-alist'. + +`#+PRIORITIES: highest lowest default' + This line sets the limits and the default for the priorities. All + three must be either letters A-Z or numbers 0-9. The highest + priority must have a lower ASCII number that the lowest priority. + `#+STARTUP:' This line sets options to be used at startup of org-mode, when an Org-mode file is being visited. The first set of options deals @@ -5604,39 +5907,11 @@ file is visited again in a new Emacs session. constcgs `constants.el' should use the c-g-s unit system constSI `constants.el' should use the SI unit system -`#+SEQ_TODO: #+TYP_TODO:' - These lines set the TODO keywords and their interpretation in the - current file. The corresponding variables are `org-todo-keywords' - and `org-todo-interpretation'. - `#+TAGS: TAG1(c1) TAG2(c2)' These lines (several such lines are allowed) specify the legal tags in this file, and (potentially) the corresponding _fast tag selection_ keys. The corresponding variable is `org-tag-alist'. -`#+LINK: linkword replace' - These lines (several are allowed) specify link abbreviations. - *Note Link abbreviations::. The corresponding variable is - `org-link-abbrev-alist'. - -`#+CATEGORY:' - This line sets the category for the agenda file. The category - applies for all subsequent lines until the next `#+CATEGORY' line, - or the end of the file. The first such line also applies to any - entries before it. - -`#+ARCHIVE: %s_done::' - This line sets the archive location for the agenda file. It - applies for all subsequent lines until the next `#+CATEGORY' line, - or the end of the file. The first such line also applies to any - entries before it. The corresponding variable is - `org-archive-location'. - -`#+PRIORITIES: highest lowest default' - This line sets the limits and the default for the priorities. All - three must be either letters A-Z or numbers 0-9. The highest - priority must have a lower ASCII number that the lowest priority. - `#+TBLFM:' This line contains the formulas for the table directly above the line. @@ -5645,10 +5920,15 @@ file is visited again in a new Emacs session. These lines provide settings for exporting files. For more details see *Note Export options::. +`#+SEQ_TODO: #+TYP_TODO:' + These lines set the TODO keywords and their interpretation in the + current file. The corresponding variables are `org-todo-keywords' + and `org-todo-interpretation'. +  File: org, Node: The very busy C-c C-c key, Next: Clean view, Prev: In-buffer settings, Up: Miscellaneous -12.4 The very busy C-c C-c key +13.4 The very busy C-c C-c key ============================== The key `C-c C-c' has many purposes in org-mode, which are all @@ -5690,7 +5970,7 @@ means in different contexts.  File: org, Node: Clean view, Next: TTY keys, Prev: The very busy C-c C-c key, Up: Miscellaneous -12.5 A cleaner outline view +13.5 A cleaner outline view =========================== Some people find it noisy and distracting that the Org-mode headlines @@ -5772,7 +6052,7 @@ org-convert-to-oddeven-levels'.  File: org, Node: TTY keys, Next: Interaction, Prev: Clean view, Up: Miscellaneous -12.6 Using org-mode on a tty +13.6 Using org-mode on a tty ============================ Org-mode uses a number of keys that are not accessible on a tty. This @@ -5814,7 +6094,7 @@ Default Alternative 1 Alternative 2  File: org, Node: Interaction, Next: Bugs, Prev: TTY keys, Up: Miscellaneous -12.7 Interaction with other packages +13.7 Interaction with other packages ==================================== Org-mode lives in the world of GNU Emacs and interacts in various ways @@ -5828,7 +6108,7 @@ with other code out there.  File: org, Node: Cooperation, Next: Conflicts, Prev: Interaction, Up: Interaction -12.7.1 Packages that Org-mode cooperates with +13.7.1 Packages that Org-mode cooperates with --------------------------------------------- `calc.el' by Dave Gillespie @@ -5890,7 +6170,7 @@ File: org, Node: Cooperation, Next: Conflicts, Prev: Interaction, Up: Intera  File: org, Node: Conflicts, Prev: Cooperation, Up: Interaction -12.7.2 Packages that lead to conflicts with Org-mode +13.7.2 Packages that lead to conflicts with Org-mode ---------------------------------------------------- `allout.el' by Ken Manheimer @@ -5934,7 +6214,7 @@ File: org, Node: Conflicts, Prev: Cooperation, Up: Interaction  File: org, Node: Bugs, Prev: Interaction, Up: Miscellaneous -12.8 Bugs +13.8 Bugs ========= Here is a list of things that should work differently, but which I have @@ -5985,6 +6265,7 @@ Org-mode. * Tables in arbitrary syntax:: Orgtbl for LaTeX and other programs * Dynamic blocks:: Automatically filled blocks * Special agenda views:: Customized views +* Using the property API:: Writing programs that use entry properties  File: org, Node: Extensions, Next: Tables in arbitrary syntax, Prev: Extensions and Hacking, Up: Extensions and Hacking @@ -6332,7 +6613,7 @@ written in a way that is does nothing in buffers that are not in Org-mode.  -File: org, Node: Special agenda views, Prev: Dynamic blocks, Up: Extensions and Hacking +File: org, Node: Special agenda views, Next: Using the property API, Prev: Dynamic blocks, Up: Extensions and Hacking A.4 Special Agenda Views ======================== @@ -6385,6 +6666,42 @@ command for producing this special list. Custom commands always supply the MATCH argument, but it can be empty if you do not specify it while defining the command(*note Custom agenda views::). + +File: org, Node: Using the property API, Prev: Special agenda views, Up: Extensions and Hacking + +A.5 Using the property API +========================== + +Here is a description of the functions that can be used to work with +properties. + + -- Function: org-entry-properties &optional pom which + Get all properties of the entry at point-or-marker POM. This + includes the TODO keyword, the tags, time strings for deadline, + scheduled, and clocking, and any additional properties defined in + the entry. The return value is an alist, keys may occur multiple + times if the property key was used several times. POM may also be + nil, in which case the current entry is used. If WHICH is nil or + `all', get all properties. If WHICH is `special' or `standard', + only get that subclass. + + -- Function: org-entry-get pom property &optional inherit + Get value of PROPERTY for entry at point-or-marker POM. If + INHERIT is non-nil and the entry does not have the property, then + also check higher levels of the hierarchy. + + -- Function: org-entry-delete pom property + Delete the property PROPERTY from entry at point-or-marker POM. + + -- Function: org-entry-put pom property value + Set PROPERTY to VALUE for entry at point-or-marker POM. + + -- Function: org-buffer-property-keys &optional include-specials + Get all property keys in the current buffer. + + -- Function: org-insert-property-drawer + Insert a property drawer at point. +  File: org, Node: History and Acknowledgments, Next: Index, Prev: Extensions and Hacking, Up: Top @@ -6408,7 +6725,7 @@ 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, hundreds of emails to me or on + Since the first release, literally thousands of emails to me or on `emacs-orgmode@gnu.org' have provided a constant stream of bug reports, feedback, new ideas, and sometimes patches and add-on code. Many thanks to everyone who has helped to improve this package. I am trying @@ -6416,6 +6733,8 @@ to keep here a list of the people who had significant influence in shaping one or more aspects of Org-mode. The list may not be complete, if I have forgotten someone, please accept my apologies and let me know. + * Russel Adams came up with the idea for drawers. + * Thomas Baumann contributed the code for links to the MH-E email system. @@ -6433,7 +6752,9 @@ if I have forgotten someone, please accept my apologies and let me know. * Sacha Chua suggested to copy some linking code from Planner. - * Eddward DeVilla proposed and tested checkbox statistics. + * 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. * Kees Dullemond used to edit projects lists directly in HTML and so inspired some of the early development, including HTML export. He @@ -6459,6 +6780,9 @@ if I have forgotten someone, please accept my apologies and let me know. * Kai Grossjohann pointed out key-binding conflicts with other packages. + * Scott Jaderholm proposed footnotes, control over whitespace between + folded entries, and column view for properties. + * Shidai Liu ("Leo") asked for embedded LaTeX and tested it. He also provided frequent feedback and some patches. @@ -6564,20 +6888,22 @@ Index * agenda: Weekly/Daily agenda. (line 6) * agenda dispatcher: Agenda dispatcher. (line 6) * agenda files: Agenda files. (line 6) -* agenda files, removing buffers: Agenda commands. (line 239) +* agenda files, removing buffers: Agenda commands. (line 236) * agenda views: Agenda views. (line 6) * agenda views, custom: Custom agenda views. (line 6) * agenda views, exporting <1>: Exporting Agenda Views. (line 6) -* agenda views, exporting: Agenda commands. (line 228) +* agenda views, exporting: Agenda commands. (line 225) * agenda views, user-defined: Special agenda views. (line 6) * agenda, pipe: Extracting Agenda Information for other programs. (line 6) * agenda, with block views: Block agenda. (line 6) -* align, STARTUP keyword: In-buffer settings. (line 29) +* align, STARTUP keyword: In-buffer settings. (line 63) * allout.el: Conflicts. (line 6) * angular brackets, around links: External links. (line 43) +* API, for properties: Using the property API. + (line 6) * archive locations: Moving subtrees. (line 21) * archiving: Archiving. (line 6) * ASCII export: ASCII export. (line 6) @@ -6598,7 +6924,7 @@ Index * calculations, in tables <1>: The spreadsheet. (line 6) * calculations, in tables: Built-in table editor. (line 141) -* calendar commands, from agenda: Agenda commands. (line 191) +* calendar commands, from agenda: Agenda commands. (line 188) * calendar integration: Weekly/Daily agenda. (line 24) * calendar, for selecting date: The date/time prompt. (line 26) @@ -6619,6 +6945,7 @@ Index * completion, of option keywords <1>: Completion. (line 6) * completion, of option keywords <2>: Export options. (line 6) * completion, of option keywords: Per file keywords. (line 23) +* completion, of property keys: Completion. (line 6) * completion, of tags <1>: Completion. (line 6) * completion, of tags: Setting tags. (line 11) * completion, of TeX symbols: Completion. (line 6) @@ -6626,9 +6953,9 @@ Index * completion, of TODO keywords: Workflow states. (line 15) * constants, in calculations: References. (line 82) * constants.el: Cooperation. (line 14) -* constcgs, STARTUP keyword: In-buffer settings. (line 54) -* constSI, STARTUP keyword: In-buffer settings. (line 54) -* content, STARTUP keyword: In-buffer settings. (line 22) +* constcgs, STARTUP keyword: In-buffer settings. (line 88) +* constSI, STARTUP keyword: In-buffer settings. (line 88) +* content, STARTUP keyword: In-buffer settings. (line 56) * contents, global visibility state: Visibility cycling. (line 22) * copying, of subtrees: Structure editing. (line 6) * creating timestamps: Creating timestamps. (line 6) @@ -6637,7 +6964,7 @@ Index * custom date/time format: Custom time format. (line 6) * custom search strings: Custom searches. (line 6) * customization: Customization. (line 6) -* customtime, STARTUP keyword: In-buffer settings. (line 51) +* customtime, STARTUP keyword: In-buffer settings. (line 85) * cutting, of subtrees: Structure editing. (line 6) * cycling, of TODO states: TODO basics. (line 13) * cycling, visibility: Visibility cycling. (line 6) @@ -6654,7 +6981,7 @@ Index * debugging, of table formulas: Editing and debugging formulas. (line 97) * demotion, of subtrees: Structure editing. (line 6) -* diary entries, creating from agenda: Agenda commands. (line 196) +* diary entries, creating from agenda: Agenda commands. (line 193) * diary integration: Weekly/Daily agenda. (line 24) * dictionary word completion: Completion. (line 6) * directories, for publishing: Sources and destinations. @@ -6663,6 +6990,7 @@ Index * display changing, in agenda: Agenda commands. (line 65) * document structure: Document structure. (line 6) * DONE, final TODO keyword: Per file keywords. (line 26) +* drawers: Drawers. (line 6) * dynamic blocks: Dynamic blocks. (line 6) * editing tables: Tables. (line 6) * editing, of table formulas: Editing and debugging formulas. @@ -6671,11 +6999,11 @@ Index * emphasized text: Export options. (line 25) * enhancing text: Enhancing text. (line 6) * evaluate time range: Creating timestamps. (line 48) -* even, STARTUP keyword: In-buffer settings. (line 44) +* even, STARTUP keyword: In-buffer settings. (line 78) * exporting: Exporting. (line 6) * exporting agenda views <1>: Exporting Agenda Views. (line 12) -* exporting agenda views: Agenda commands. (line 228) +* exporting agenda views: Agenda commands. (line 225) * exporting, not: Comment lines. (line 6) * extended TODO keywords: TODO extensions. (line 6) * extension, third-party: Extensions. (line 6) @@ -6730,7 +7058,7 @@ Index * headline, promotion and demotion: Structure editing. (line 6) * headlines: Headlines. (line 6) * hide text: Visibility cycling. (line 6) -* hidestars, STARTUP keyword: In-buffer settings. (line 44) +* hidestars, STARTUP keyword: In-buffer settings. (line 78) * hiding leading stars: Clean view. (line 6) * history: History and Acknowledgments. (line 6) @@ -6784,16 +7112,18 @@ Index * lists, hand-formatted: Enhancing text. (line 11) * lists, ordered: Plain lists. (line 6) * lists, plain: Plain lists. (line 6) -* logdone, STARTUP keyword: In-buffer settings. (line 33) +* logdone, STARTUP keyword: In-buffer settings. (line 67) * logging, of progress: Progress logging. (line 6) -* lognoteclock-out, STARTUP keyword: In-buffer settings. (line 33) -* lognotedone, STARTUP keyword: In-buffer settings. (line 33) -* lognotestate, STARTUP keyword: In-buffer settings. (line 33) -* logrepeat, STARTUP keyword: In-buffer settings. (line 33) +* lognoteclock-out, STARTUP keyword: In-buffer settings. (line 67) +* lognotedone, STARTUP keyword: In-buffer settings. (line 67) +* lognotestate, STARTUP keyword: In-buffer settings. (line 67) +* logrepeat, STARTUP keyword: In-buffer settings. (line 67) * maintainer: Feedback. (line 6) * mark ring: Handling links. (line 81) * marking characters, tables: Advanced features. (line 40) -* matching, of tags: Matching headline tags. +* matching, of properties: Matching tags and properties. + (line 6) +* matching, of tags: Matching tags and properties. (line 6) * matching, tags: Tags. (line 6) * math symbols: Math symbols. (line 6) @@ -6807,11 +7137,11 @@ Index * named references: References. (line 82) * names as TODO keywords: TODO types. (line 6) * narrow columns in tables: Narrow columns. (line 6) -* noalign, STARTUP keyword: In-buffer settings. (line 29) -* nologging, STARTUP keyword: In-buffer settings. (line 33) -* nologrepeat, STARTUP keyword: In-buffer settings. (line 33) +* noalign, STARTUP keyword: In-buffer settings. (line 63) +* nologging, STARTUP keyword: In-buffer settings. (line 67) +* nologrepeat, STARTUP keyword: In-buffer settings. (line 67) * occur, command: Sparse trees. (line 6) -* odd, STARTUP keyword: In-buffer settings. (line 44) +* odd, STARTUP keyword: In-buffer settings. (line 78) * option keyword completion: Completion. (line 6) * options, for custom agenda views: Setting Options. (line 6) * options, for customization: Customization. (line 6) @@ -6832,7 +7162,7 @@ Index * outline-mode: Outlines. (line 6) * outlines: Outlines. (line 6) * overview, global visibility state: Visibility cycling. (line 22) -* overview, STARTUP keyword: In-buffer settings. (line 22) +* overview, STARTUP keyword: In-buffer settings. (line 56) * packages, interaction with other: Interaction. (line 6) * pasting, of subtrees: Structure editing. (line 6) * per file keywords: Per file keywords. (line 6) @@ -6847,6 +7177,7 @@ Index * progress logging: Progress logging. (line 6) * projects, for publishing: Project alist. (line 6) * promotion, of subtrees: Structure editing. (line 6) +* properties: Properties. (line 6) * publishing: Publishing. (line 6) * quoted HTML tags: Export options. (line 25) * radio tables: Radio tables. (line 6) @@ -6866,8 +7197,8 @@ Index * regular expressions, with tags search: Tag searches. (line 63) * remember.el <1>: Cooperation. (line 33) * remember.el: Remember. (line 6) -* remote editing, from agenda: Agenda commands. (line 106) -* remote editing, undo: Agenda commands. (line 107) +* remote editing, from agenda: Agenda commands. (line 103) +* remote editing, undo: Agenda commands. (line 104) * richer text: Enhancing text. (line 6) * RMAIL links: External links. (line 6) * SCHEDULED keyword: Deadlines and scheduling. @@ -6884,8 +7215,8 @@ Index * show all, command: Visibility cycling. (line 33) * show all, global visibility state: Visibility cycling. (line 22) * show hidden text: Visibility cycling. (line 6) -* showall, STARTUP keyword: In-buffer settings. (line 22) -* showstars, STARTUP keyword: In-buffer settings. (line 44) +* showall, STARTUP keyword: In-buffer settings. (line 56) +* showstars, STARTUP keyword: In-buffer settings. (line 78) * sorting, of agenda items: Sorting of agenda items. (line 6) * sparse tree, for deadlines: Inserting deadline/schedule. @@ -6926,7 +7257,7 @@ Index * tag completion: Completion. (line 6) * tag searches: Tag searches. (line 6) * tags: Tags. (line 6) -* tags view: Matching headline tags. +* tags view: Matching tags and properties. (line 6) * tags, setting: Setting tags. (line 6) * targets, for links: Internal links. (line 6) @@ -6978,7 +7309,7 @@ Index * tty keybindings: TTY keys. (line 6) * types as TODO keywords: TODO types. (line 6) * underlined text: Enhancing text. (line 15) -* undoing remote-editing events: Agenda commands. (line 107) +* undoing remote-editing events: Agenda commands. (line 104) * updating, table: Updating the table. (line 6) * URL links: External links. (line 6) * USENET links: External links. (line 6) @@ -7004,23 +7335,23 @@ Key Index [index] * Menu: -* $: Agenda commands. (line 121) +* $: Agenda commands. (line 118) * ': CDLaTeX mode. (line 43) -* +: Agenda commands. (line 143) -* ,: Agenda commands. (line 135) -* -: Agenda commands. (line 149) -* .: Agenda commands. (line 98) -* :: Agenda commands. (line 129) +* +: Agenda commands. (line 140) +* ,: Agenda commands. (line 132) +* -: Agenda commands. (line 146) +* .: Agenda commands. (line 95) +* :: Agenda commands. (line 126) * <: The date/time prompt. (line 32) -* : Agenda commands. (line 95) +* : Agenda commands. (line 92) * <1>: Agenda commands. (line 39) * <2>: The date/time prompt. (line 57) * <3>: Setting tags. (line 76) * : Built-in table editor. (line 62) -* : Agenda commands. (line 90) +* : Agenda commands. (line 87) * <1>: Agenda commands. (line 28) * : Setting tags. (line 73) * <1>: CDLaTeX mode. (line 23) @@ -7032,20 +7363,20 @@ Key Index (line 55) * <6>: Plain lists. (line 41) * : Visibility cycling. (line 10) -* > <1>: Agenda commands. (line 171) +* > <1>: Agenda commands. (line 168) * >: The date/time prompt. (line 33) * ^: CDLaTeX mode. (line 33) * _: CDLaTeX mode. (line 33) * `: CDLaTeX mode. (line 39) -* a: Agenda commands. (line 132) +* a: Agenda commands. (line 129) * b: Agenda commands. (line 49) -* C: Agenda commands. (line 211) -* c: Agenda commands. (line 191) +* C: Agenda commands. (line 208) +* c: Agenda commands. (line 188) * C-#: Advanced features. (line 9) * C-': Agenda files. (line 18) * C-,: Agenda files. (line 18) -* C-_: Agenda commands. (line 107) +* C-_: Agenda commands. (line 104) * C-a a L: Timeline. (line 10) * C-c ! <1>: Footnotes. (line 14) * C-c !: Creating timestamps. (line 19) @@ -7058,8 +7389,9 @@ Key Index * C-c +: Built-in table editor. (line 141) * C-c ,: Priorities. (line 18) -* C-c -: Built-in table editor. +* C-c - <1>: Built-in table editor. (line 90) +* C-c -: Plain lists. (line 88) * C-c .: Creating timestamps. (line 10) * C-c /: Sparse trees. (line 15) * C-c :: Enhancing text. (line 32) @@ -7087,9 +7419,9 @@ Key Index * C-c a C: Storing searches. (line 9) * C-c a e: Exporting Agenda Views. (line 57) -* C-c a M: Matching headline tags. +* C-c a M: Matching tags and properties. (line 15) -* C-c a m: Matching headline tags. +* C-c a m: Matching tags and properties. (line 10) * C-c a M: Tag searches. (line 16) * C-c a m: Tag searches. (line 12) @@ -7110,7 +7442,7 @@ Key Index * C-c C-c <7>: Built-in table editor. (line 54) * C-c C-c: Plain lists. (line 81) -* C-c C-d <1>: Agenda commands. (line 156) +* C-c C-d <1>: Agenda commands. (line 153) * C-c C-d: Inserting deadline/schedule. (line 9) * C-c C-e: Exporting. (line 19) @@ -7145,7 +7477,7 @@ Key Index * C-c C-r <1>: Editing and debugging formulas. (line 53) * C-c C-r: Visibility cycling. (line 34) -* C-c C-s <1>: Agenda commands. (line 153) +* C-c C-s <1>: Agenda commands. (line 150) * C-c C-s: Inserting deadline/schedule. (line 18) * C-c C-t <1>: Clocking work time. (line 27) @@ -7157,7 +7489,8 @@ Key Index * C-c C-x b: Visibility cycling. (line 41) * C-c C-x C-a: ARCHIVE tag. (line 28) * C-c C-x C-b: Checkboxes. (line 38) -* C-c C-x C-c: Agenda commands. (line 218) +* C-c C-x C-c <1>: Agenda commands. (line 215) +* C-c C-x C-c: Using column view. (line 6) * C-c C-x C-d: Clocking work time. (line 35) * C-c C-x C-i: Clocking work time. (line 12) * C-c C-x C-k: Structure editing. (line 39) @@ -7191,7 +7524,7 @@ Key Index * C-c }: Editing and debugging formulas. (line 28) * C-c ~: Cooperation. (line 48) -* C-k: Agenda commands. (line 115) +* C-k: Agenda commands. (line 112) * C-S-: Multiple sets in one file. (line 25) * C-S-: Multiple sets in one file. @@ -7215,17 +7548,19 @@ Key Index (line 46) * C-x C-w <1>: Exporting Agenda Views. (line 11) -* C-x C-w: Agenda commands. (line 227) -* D: Agenda commands. (line 72) -* d: Agenda commands. (line 69) +* C-x C-w: Agenda commands. (line 224) +* D: Agenda commands. (line 69) +* d: Agenda commands. (line 66) +* e: Using column view. (line 13) * f: Agenda commands. (line 42) -* g: Agenda commands. (line 76) -* H: Agenda commands. (line 215) -* i: Agenda commands. (line 196) -* I: Agenda commands. (line 176) +* g: Agenda commands. (line 73) +* H: Agenda commands. (line 212) +* i: Agenda commands. (line 193) +* I: Agenda commands. (line 173) * l: Agenda commands. (line 55) * L: Agenda commands. (line 30) -* M: Agenda commands. (line 202) +* M: Agenda commands. (line 199) +* m: Agenda commands. (line 66) * M- <1>: Editing and debugging formulas. (line 76) * M-: Built-in table editor. @@ -7239,8 +7574,9 @@ Key Index (line 72) * M-: Structure editing. (line 24) * M- <1>: Completion. (line 10) -* M- <2>: Setting tags. (line 6) -* M- <3>: Per file keywords. (line 23) +* M- <2>: Property syntax. (line 22) +* M- <3>: Setting tags. (line 6) +* M- <4>: Per file keywords. (line 23) * M-: Editing and debugging formulas. (line 64) * M- <1>: Editing and debugging formulas. @@ -7283,16 +7619,17 @@ Key Index * mouse-3 <1>: Agenda commands. (line 28) * mouse-3: Handling links. (line 77) * n: Agenda commands. (line 19) -* O: Agenda commands. (line 180) +* O: Agenda commands. (line 177) * o: Agenda commands. (line 65) -* P: Agenda commands. (line 140) +* P: Agenda commands. (line 137) * p: Agenda commands. (line 20) -* q: Agenda commands. (line 238) -* r <1>: Agenda commands. (line 80) +* q <1>: Agenda commands. (line 235) +* q: Using column view. (line 23) +* r <1>: Agenda commands. (line 77) * r: Global TODO list. (line 22) -* S: Agenda commands. (line 206) -* s: Agenda commands. (line 87) -* S- <1>: Agenda commands. (line 149) +* S: Agenda commands. (line 203) +* s: Agenda commands. (line 84) +* S- <1>: Agenda commands. (line 146) * S- <2>: The date/time prompt. (line 45) * S- <3>: Creating timestamps. (line 40) @@ -7300,7 +7637,7 @@ Key Index * S- <5>: Editing and debugging formulas. (line 67) * S-: Plain lists. (line 62) -* S- <1>: Agenda commands. (line 167) +* S- <1>: Agenda commands. (line 164) * S- <2>: The date/time prompt. (line 42) * S- <3>: Creating timestamps. (line 35) @@ -7311,7 +7648,7 @@ Key Index (line 67) * S-: Built-in table editor. (line 144) -* S- <1>: Agenda commands. (line 159) +* S- <1>: Agenda commands. (line 156) * S- <2>: The date/time prompt. (line 39) * S- <3>: Creating timestamps. (line 35) @@ -7323,7 +7660,7 @@ Key Index * S- <1>: Built-in table editor. (line 59) * S-: Visibility cycling. (line 22) -* S- <1>: Agenda commands. (line 143) +* S- <1>: Agenda commands. (line 140) * S- <2>: The date/time prompt. (line 48) * S- <3>: Creating timestamps. (line 40) @@ -7331,204 +7668,217 @@ Key Index * S- <5>: Editing and debugging formulas. (line 67) * S-: Plain lists. (line 62) -* T: Agenda commands. (line 124) -* t: Agenda commands. (line 111) +* S-M-: TODO basics. (line 44) +* T: Agenda commands. (line 121) +* t: Agenda commands. (line 108) +* v: Using column view. (line 19) * w: Agenda commands. (line 66) -* x: Agenda commands. (line 239) -* X: Agenda commands. (line 183) +* x: Agenda commands. (line 236) +* X: Agenda commands. (line 180) +* y: Agenda commands. (line 66)  Tag Table: Node: Top970 -Node: Introduction11743 -Node: Summary12158 -Node: Installation15167 -Node: Activation16545 -Node: Feedback17794 -Node: Document structure19870 -Node: Outlines20644 -Node: Headlines21304 -Ref: Headlines-Footnote-122312 -Node: Visibility cycling22411 -Ref: Visibility cycling-Footnote-124621 -Ref: Visibility cycling-Footnote-224679 -Ref: Visibility cycling-Footnote-324729 -Node: Motion24999 -Node: Structure editing25953 -Node: Archiving28779 -Node: ARCHIVE tag29337 -Node: Moving subtrees31130 -Node: Sparse trees32441 -Ref: Sparse trees-Footnote-134573 -Ref: Sparse trees-Footnote-234755 -Node: Plain lists34870 -Ref: Plain lists-Footnote-138868 -Ref: Plain lists-Footnote-239226 -Node: Tables39407 -Node: Built-in table editor39988 -Node: Narrow columns47227 -Ref: Narrow columns-Footnote-149162 -Node: Column groups49208 -Node: orgtbl-mode50741 -Node: The spreadsheet51544 -Node: References52631 -Ref: References-Footnote-156760 -Node: Formula syntax for Calc57049 -Node: Formula syntax for Lisp59506 -Node: Field formulas61224 -Node: Column formulas62532 -Node: Editing and debugging formulas64131 -Node: Updating the table68284 -Node: Advanced features69319 -Node: Hyperlinks73844 -Node: Link format74617 -Node: Internal links75910 -Ref: Internal links-Footnote-177835 -Node: Radio targets77970 -Node: External links78661 -Node: Handling links81065 -Ref: Handling links-Footnote-186352 -Ref: Handling links-Footnote-286589 -Node: Link abbreviations86663 -Node: Search options88342 -Ref: Search options-Footnote-190122 -Node: Custom searches90203 -Node: Remember91251 -Node: Setting up remember92238 -Node: Remember templates92820 -Ref: Remember templates-Footnote-196112 -Node: Storing notes96210 -Node: TODO items98097 -Node: TODO basics99074 -Node: TODO extensions100771 -Node: Workflow states101590 -Ref: Workflow states-Footnote-1102765 -Node: TODO types102858 -Ref: TODO types-Footnote-1104441 -Node: Multiple sets in one file104523 -Node: Per file keywords106134 -Ref: Per file keywords-Footnote-1107423 -Node: Priorities107624 -Node: Breaking down tasks109234 -Ref: Breaking down tasks-Footnote-1109754 -Node: Checkboxes109850 -Node: Tags112605 -Node: Tag inheritance113365 -Node: Setting tags114302 -Ref: Setting tags-Footnote-1118825 -Ref: Setting tags-Footnote-2118937 -Node: Tag searches119020 -Node: Timestamps121731 -Node: Time stamps122174 -Ref: Time stamps-Footnote-1124602 -Node: Creating timestamps124718 -Node: The date/time prompt126792 -Ref: The date/time prompt-Footnote-1128780 -Node: Custom time format128886 -Node: Deadlines and scheduling130578 -Ref: Deadlines and scheduling-Footnote-1131928 -Node: Inserting deadline/schedule132083 -Node: Repeated tasks133021 -Node: Progress logging134660 -Node: Closing items135315 -Ref: Closing items-Footnote-1136249 -Ref: Closing items-Footnote-2136318 -Node: Tracking TODO state changes136391 -Node: Clocking work time137247 -Ref: Clocking work time-Footnote-1140893 -Ref: Clocking work time-Footnote-2140971 -Node: Agenda views141097 -Node: Agenda files143048 -Ref: Agenda files-Footnote-1144014 -Ref: Agenda files-Footnote-2144163 -Node: Agenda dispatcher144356 -Node: Built-in agenda views146047 -Node: Weekly/Daily agenda146625 -Node: Global TODO list149566 -Node: Matching headline tags151838 -Node: Timeline152909 -Node: Stuck projects153575 -Node: Presentation and sorting155426 -Node: Categories156217 -Node: Time-of-day specifications156881 -Node: Sorting of agenda items158852 -Node: Agenda commands160134 -Node: Custom agenda views167288 -Node: Storing searches168007 -Node: Block agenda169919 -Node: Setting Options171149 -Node: Exporting Agenda Views173888 -Ref: Exporting Agenda Views-Footnote-1178172 -Ref: Exporting Agenda Views-Footnote-2178229 -Node: Extracting Agenda Information for other programs178415 -Node: Embedded LaTeX182541 -Ref: Embedded LaTeX-Footnote-1183633 -Node: Math symbols183823 -Node: Subscripts and Superscripts184588 -Node: LaTeX fragments185432 -Ref: LaTeX fragments-Footnote-1187666 -Node: Processing LaTeX fragments187928 -Node: CDLaTeX mode188874 -Ref: CDLaTeX mode-Footnote-1191358 -Node: Exporting191506 -Node: ASCII export192820 -Node: HTML export194110 -Node: Export commands194729 -Node: Quoting HTML tags195973 -Node: Links196603 -Node: Images197300 -Ref: Images-Footnote-1198171 -Node: CSS support198232 -Ref: CSS support-Footnote-1199551 -Node: XOXO export199664 -Node: iCalendar export200103 -Node: Text interpretation201322 -Node: Comment lines201913 -Node: Initial text202308 -Node: Footnotes203977 -Node: Enhancing text204792 -Ref: Enhancing text-Footnote-1206651 -Node: Export options206741 -Node: Publishing208686 -Ref: Publishing-Footnote-1209482 -Node: Configuration209678 -Node: Project alist210396 -Node: Sources and destinations211462 -Node: Selecting files212192 -Node: Publishing action212940 -Node: Publishing options214173 -Node: Publishing links216325 -Node: Project page index217838 -Node: Sample configuration218616 -Node: Simple example219108 -Node: Complex example219781 -Node: Triggering publication221857 -Node: Miscellaneous222542 -Node: Completion223176 -Node: Customization224647 -Node: In-buffer settings225230 -Node: The very busy C-c C-c key230106 -Node: Clean view231750 -Node: TTY keys234327 -Node: Interaction235937 -Node: Cooperation236334 -Node: Conflicts239210 -Node: Bugs241213 -Node: Extensions and Hacking242709 -Node: Extensions243305 -Node: Tables in arbitrary syntax245252 -Node: Radio tables246329 -Node: A LaTeX example248832 -Ref: A LaTeX example-Footnote-1252478 -Ref: A LaTeX example-Footnote-2252626 -Node: Translator functions253061 -Ref: Translator functions-Footnote-1256170 -Node: Dynamic blocks256258 -Node: Special agenda views258230 -Ref: Special agenda views-Footnote-1260509 -Node: History and Acknowledgments260769 -Node: Index266863 -Node: Key Index299090 +Node: Introduction12310 +Node: Summary12725 +Node: Installation15734 +Node: Activation17112 +Node: Feedback18361 +Node: Document structure20437 +Node: Outlines21223 +Node: Headlines21883 +Ref: Headlines-Footnote-122891 +Node: Visibility cycling22990 +Ref: Visibility cycling-Footnote-125200 +Ref: Visibility cycling-Footnote-225258 +Ref: Visibility cycling-Footnote-325308 +Node: Motion25578 +Node: Structure editing26532 +Node: Archiving29358 +Node: ARCHIVE tag29916 +Node: Moving subtrees31709 +Node: Sparse trees33020 +Ref: Sparse trees-Footnote-135152 +Ref: Sparse trees-Footnote-235334 +Node: Plain lists35449 +Ref: Plain lists-Footnote-139646 +Ref: Plain lists-Footnote-240004 +Node: Drawers40185 +Node: Tables41026 +Node: Built-in table editor41607 +Node: Narrow columns48846 +Ref: Narrow columns-Footnote-150781 +Node: Column groups50827 +Node: orgtbl-mode52360 +Node: The spreadsheet53163 +Node: References54250 +Ref: References-Footnote-158701 +Node: Formula syntax for Calc58990 +Node: Formula syntax for Lisp61447 +Node: Field formulas63165 +Node: Column formulas64473 +Node: Editing and debugging formulas66072 +Node: Updating the table70225 +Node: Advanced features71260 +Node: Hyperlinks75785 +Node: Link format76558 +Node: Internal links77851 +Ref: Internal links-Footnote-179776 +Node: Radio targets79911 +Node: External links80602 +Node: Handling links83006 +Ref: Handling links-Footnote-188293 +Ref: Handling links-Footnote-288530 +Node: Link abbreviations88604 +Node: Search options90283 +Ref: Search options-Footnote-192063 +Node: Custom searches92144 +Node: Remember93192 +Node: Setting up remember94179 +Node: Remember templates94761 +Ref: Remember templates-Footnote-198207 +Node: Storing notes98305 +Node: TODO items100192 +Node: TODO basics101169 +Node: TODO extensions102933 +Node: Workflow states103752 +Ref: Workflow states-Footnote-1104927 +Node: TODO types105020 +Ref: TODO types-Footnote-1106603 +Node: Multiple sets in one file106685 +Node: Per file keywords108296 +Ref: Per file keywords-Footnote-1109585 +Node: Priorities109786 +Node: Breaking down tasks111396 +Ref: Breaking down tasks-Footnote-1111916 +Node: Checkboxes112012 +Node: Tags114767 +Node: Tag inheritance115527 +Node: Setting tags116464 +Ref: Setting tags-Footnote-1120987 +Ref: Setting tags-Footnote-2121099 +Node: Tag searches121182 +Node: Properties123899 +Node: Property syntax124884 +Node: Special properties125705 +Node: Property searches126366 +Node: Column view127009 +Node: Defining columns128199 +Node: Using column view130710 +Node: Property API131627 +Node: Timestamps131969 +Node: Time stamps132418 +Ref: Time stamps-Footnote-1134846 +Node: Creating timestamps134962 +Node: The date/time prompt137036 +Ref: The date/time prompt-Footnote-1139024 +Node: Custom time format139130 +Node: Deadlines and scheduling140822 +Ref: Deadlines and scheduling-Footnote-1142172 +Node: Inserting deadline/schedule142327 +Node: Repeated tasks143265 +Node: Progress logging144904 +Node: Closing items145559 +Ref: Closing items-Footnote-1146493 +Ref: Closing items-Footnote-2146562 +Node: Tracking TODO state changes146635 +Node: Clocking work time147491 +Ref: Clocking work time-Footnote-1151137 +Ref: Clocking work time-Footnote-2151215 +Node: Agenda views151341 +Node: Agenda files153292 +Ref: Agenda files-Footnote-1154258 +Ref: Agenda files-Footnote-2154407 +Node: Agenda dispatcher154600 +Node: Built-in agenda views156297 +Node: Weekly/Daily agenda156877 +Node: Global TODO list159819 +Node: Matching tags and properties162097 +Node: Timeline163186 +Node: Stuck projects163858 +Node: Presentation and sorting165709 +Node: Categories166500 +Node: Time-of-day specifications167164 +Node: Sorting of agenda items169135 +Node: Agenda commands170417 +Node: Custom agenda views177503 +Node: Storing searches178222 +Node: Block agenda180134 +Node: Setting Options181364 +Node: Exporting Agenda Views184103 +Ref: Exporting Agenda Views-Footnote-1188387 +Ref: Exporting Agenda Views-Footnote-2188444 +Node: Extracting Agenda Information for other programs188630 +Node: Embedded LaTeX192756 +Ref: Embedded LaTeX-Footnote-1193850 +Node: Math symbols194040 +Node: Subscripts and Superscripts194807 +Node: LaTeX fragments195653 +Ref: LaTeX fragments-Footnote-1197889 +Node: Processing LaTeX fragments198151 +Node: CDLaTeX mode199099 +Ref: CDLaTeX mode-Footnote-1201585 +Node: Exporting201733 +Node: ASCII export203047 +Node: HTML export204337 +Node: Export commands204956 +Node: Quoting HTML tags206200 +Node: Links206830 +Node: Images207527 +Ref: Images-Footnote-1208398 +Node: CSS support208459 +Ref: CSS support-Footnote-1209778 +Node: XOXO export209891 +Node: iCalendar export210330 +Node: Text interpretation211549 +Node: Comment lines212140 +Node: Initial text212535 +Node: Footnotes214204 +Node: Enhancing text215019 +Ref: Enhancing text-Footnote-1216878 +Node: Export options216968 +Node: Publishing218913 +Ref: Publishing-Footnote-1219709 +Node: Configuration219905 +Node: Project alist220623 +Node: Sources and destinations221689 +Node: Selecting files222419 +Node: Publishing action223167 +Node: Publishing options224400 +Node: Publishing links226552 +Node: Project page index228065 +Node: Sample configuration228843 +Node: Simple example229335 +Node: Complex example230008 +Node: Triggering publication232084 +Node: Miscellaneous232769 +Node: Completion233403 +Node: Customization235073 +Node: In-buffer settings235656 +Node: The very busy C-c C-c key240989 +Node: Clean view242633 +Node: TTY keys245210 +Node: Interaction246820 +Node: Cooperation247217 +Node: Conflicts250093 +Node: Bugs252096 +Node: Extensions and Hacking253592 +Node: Extensions254263 +Node: Tables in arbitrary syntax256210 +Node: Radio tables257287 +Node: A LaTeX example259790 +Ref: A LaTeX example-Footnote-1263436 +Ref: A LaTeX example-Footnote-2263584 +Node: Translator functions264019 +Ref: Translator functions-Footnote-1267128 +Node: Dynamic blocks267216 +Node: Special agenda views269188 +Ref: Special agenda views-Footnote-1271498 +Node: Using the property API271758 +Node: History and Acknowledgments273239 +Node: Index279623 +Node: Key Index312363  End Tag Table diff --git a/org-install.el b/org-install.el index 31b626cd3..e5a7905ac 100644 --- a/org-install.el +++ b/org-install.el @@ -6,6 +6,8 @@ (autoload 'org-store-link "org" "Store a link to the current location." t) (autoload 'orgtbl-mode "org" "Org tables as a minor mode." t) (autoload 'turn-on-orgtbl "org" "Org tables as a minor mode.") +(autoload 'orgstruct-mode "org" "Org structure as a minor mode." t) +(autoload 'turn-on-orgstruct "org" "Org structure as a minor mode.") (autoload 'org-cycle "org" "Subtree visibility cycling." t) (autoload 'org-global-cycle "org" "Global visibility cycling." t) (autoload 'org-agenda-list "org" "Produce calendar-like agenda view." t) diff --git a/org.el b/org.el index c51e8c85f..30d0fc6ed 100644 --- a/org.el +++ b/org.el @@ -5,7 +5,7 @@ ;; Author: Carsten Dominik ;; Keywords: outlines, hypermedia, calendar, wp ;; Homepage: http://www.astro.uva.nl/~dominik/Tools/org/ -;; Version: 4.79 +;; Version: 5.01 ;; ;; This file is part of GNU Emacs. ;; @@ -83,7 +83,7 @@ ;;; Version -(defconst org-version "4.78" +(defconst org-version "5.01" "The version number of the file org.el.") (defun org-version () (interactive) @@ -97,6 +97,11 @@ (get-text-property 0 'test (format "%s" x))) "Does format transport text properties?") +(defmacro org-unmodified (&rest body) + "Execute body without changing buffer-modified-p." + `(set-buffer-modified-p + (prog1 (buffer-modified-p) ,@body))) + (defmacro org-re (s) "Replace posix classes in regular expression." (if (featurep 'xemacs) @@ -107,6 +112,14 @@ ss)) s)) +(defmacro org-preserve-lc (&rest body) + `(let ((_line (org-current-line)) + (_col (current-column))) + (unwind-protect + (progn ,@body) + (goto-line _line) + (move-to-column _col)))) + ;;; The custom variables (defgroup org nil @@ -261,6 +274,11 @@ Changes become only effective after restarting Emacs." :group 'org-keywords :type 'string) +(defcustom org-archived-string "ARCHIVED:" + "String used as the prefix for timestamps logging archiving a TODO entry." + :group 'org-keywords + :type 'string) + (defcustom org-clock-string "CLOCK:" "String used as prefix for timestamps clocking work hours on an item." :group 'org-keywords @@ -398,13 +416,15 @@ contexts. See `org-show-hierarchy-above' for valid contexts." :tag "Org Cycle" :group 'org-structure) -(defcustom org-drawers nil +(defcustom org-drawers '("PROPERTIES") "Names of drawers. Drawers are not opened by cycling on the headline above. Drawers only open with a TAB on the drawer line itself. A drawer looks like this: :DRAWERNAME: ..... - :END:" + :END: +The drawer \"PROPERTIES\" is special for capturing properties through +the property API." :group 'org-structure :type '(repeat (string :tag "Drawer Name"))) @@ -677,10 +697,7 @@ line like :type 'boolean) (defcustom org-archive-stamp-time t - "Non-nil means, add a time stamp to entries moved to an archive file. -The time stamp will be added directly after the TODO state keyword in the -first line, so it is probably best to use this in combinations with -`org-archive-mark-done'." + "Non-nil means, add a time stamp to entries moved to an archive file." :group 'org-archive :type 'boolean) @@ -901,8 +918,6 @@ from the `constants.el' package." :group 'org-table-calculation :type 'boolean) -;; FIXME this is also a variable that makes Org-mode files non-portable -;; Maybe I should have a #+ options for constants? (defcustom org-table-formula-constants nil "Alist with constant names and values, for use in table formulas. The car of each element is a name of a constant, without the `$' before it. @@ -911,12 +926,20 @@ speed of light in a formula, you would configure (setq org-table-formula-constants '((\"c\" . \"299792458.\"))) -and then use it in an equation like `$1*$c'." +and then use it in an equation like `$1*$c'. + +Constants can also be defined on a per-file basis using a line like + +#+CONSTANTS: c=299792458. pi=3.14 eps=2.4e-6" :group 'org-table-calculation :type '(repeat (cons (string :tag "name") (string :tag "value")))) +(defvar org-table-formula-constants-local nil + "Local version of `org-table-formula-constants'.") +(make-variable-buffer-local 'org-table-formula-constants-local) + (defcustom org-table-allow-automatic-line-recalculation t "Non-nil means, lines marked with |#| or |*| will be recomputed automatically. Automatically means, when TAB or RET or C-c C-c are pressed in the line." @@ -1321,7 +1344,7 @@ When not nil, this is a list of 4-element lists. In each entry, the first element is a character, a unique key to select this template. The second element is the template. The third element is optional and can specify a destination file for remember items created with this template. -The default file is given by `org-default-notes-file'. An optional third +The default file is given by `org-default-notes-file'. An optional forth element can specify the headline in that file that should be offered first when the user is asked to file the entry. The default headline is given in the variable `org-remember-default-headline'. @@ -1727,6 +1750,28 @@ make sure all corresponding TODO items find their way into the list." (defvar org-last-tags-completion-table nil "The last used completion table for tags.") +(defgroup org-properties nil + "Options concerning properties in Org-mode." + :tag "Org Properties" + :group 'org) + +(defcustom org-property-format "%-10s %s" + "How property key/value pairs should be formatted by `indent-line'. +When `indent-line' hits a property definition, it will format the line +according to this format, mainly to make sure that the values are +lined-up with respect to each other." + :group 'org-properties + :type 'string) + +(defcustom org-default-columns-format "%25ITEM %TODO %3PRIORITY %TAGS" + "The default column format, if no other format has been defined. +This variable can be set on the per-file basis by inserting a line + +#+COLUMNS: %25ITEM ....." + :group 'org-properties + :type 'string) + + (defgroup org-agenda nil "Options concerning agenda views in Org-mode." :tag "Org Agenda" @@ -2565,6 +2610,14 @@ contents entries, but still be shown in the headlines of the document." (const :tag "Not in TOC" not-in-toc) (const :tag "On" t))) +(defcustom org-export-with-property-drawer nil + "Non-nil means, export property drawers. +When nil, these drawers are removed before export. + +This option can also be set with the +OPTIONS line, e.g. \"p:t\"." + :group 'org-export-general + :type 'boolean) + (defgroup org-export-translation nil "Options for translating special ascii sequences for the export backends." :tag "Org Export Translation" @@ -3164,6 +3217,33 @@ color of the frame." "Face used for special keywords." :group 'org-faces) +(defface org-drawer ;; font-lock-function-name-face + (org-compatible-face + '((((class color) (min-colors 88) (background light)) (:foreground "Blue1")) + (((class color) (min-colors 88) (background dark)) (:foreground "LightSkyBlue")) + (((class color) (min-colors 16) (background light)) (:foreground "Blue")) + (((class color) (min-colors 16) (background dark)) (:foreground "LightSkyBlue")) + (((class color) (min-colors 8)) (:foreground "blue" :bold t)) + (t (:bold t)))) + "Face used for drawers." + :group 'org-faces) + +(defface org-property-value nil + "Face used for the value of a property." + :group 'org-faces) + +(defface org-column + (org-compatible-face + '((((class color) (min-colors 16) (background light)) + (:background "grey90")) + (((class color) (min-colors 16) (background dark)) + (:background "grey30")) + (((class color) (min-colors 8)) + (:background "cyan" :foreground "black")) + (t (:inverse-video t)))) + "Face for column display of entry properties." + :group 'org-faces) + (defface org-warning ;; font-lock-warning-face (org-compatible-face '((((class color) (min-colors 16) (background light)) (:foreground "Red1" :bold t)) @@ -3396,7 +3476,9 @@ Also put tags into group 4 if tags are present.") (match-string-no-properties num string))) (defsubst org-no-properties (s) - (remove-text-properties 0 (length s) org-rm-props s) + (if (fboundp 'set-text-properties) + (set-text-properties 0 (length s) nil s) + (remove-text-properties 0 (length s) org-rm-props s)) s) (defsubst org-get-alist-option (option key) @@ -3468,10 +3550,11 @@ means to push this value onto the list in the variable.") (org-set-local 'org-todo-heads nil) (org-set-local 'org-todo-sets nil) (let ((re (org-make-options-regexp - '("CATEGORY" "SEQ_TODO" "PRI_TODO" "TYP_TODO" - "STARTUP" "ARCHIVE" "TAGS" "LINK" "PRIORITIES"))) + '("CATEGORY" "SEQ_TODO" "PRI_TODO" "TYP_TODO" "COLUMNS" + "STARTUP" "ARCHIVE" "TAGS" "LINK" "PRIORITIES" + "CONSTANTS"))) (splitre "[ \t]+") - kwds key value cat arch tags links hw dws tail sep kws1 prio) + kwds key value cat arch tags const links hw dws tail sep kws1 prio) (save-excursion (save-restriction (widen) @@ -3489,6 +3572,8 @@ means to push this value onto the list in the variable.") (push (cons 'type (org-split-string value splitre)) kwds)) ((equal key "TAGS") (setq tags (append tags (org-split-string value splitre)))) + ((equal key "COLUMNS") + (org-set-local 'org-default-columns-format value)) ((equal key "LINK") (when (string-match "^\\(\\S-+\\)[ \t]+\\(.+\\)" value) (push (cons (match-string 1 value) @@ -3496,6 +3581,8 @@ means to push this value onto the list in the variable.") links))) ((equal key "PRIORITIES") (setq prio (org-split-string value " +"))) + ((equal key "CONSTANTS") + (setq const (append const (org-split-string value splitre)))) ((equal key "STARTUP") (let ((opts (org-split-string value splitre)) l var val) @@ -3546,6 +3633,14 @@ means to push this value onto the list in the variable.") (setq org-todo-keywords-1 (append org-todo-keywords-1 kws1 nil))) (setq org-todo-sets (nreverse org-todo-sets) org-todo-kwd-alist (nreverse org-todo-kwd-alist))) + ;; Process the constants + (when const + (let (e cst) + (while (setq e (pop const)) + (if (string-match "^\\([a-zA-Z0][_a-zA-Z0-9]*\\)=\\(.*\\)" e) + (push (cons (match-string 1 e) (match-string 2 e)) cst))) + (setq org-table-formula-constants-local cst))) + ;; Process the tags. (when tags (let (e tgs) @@ -3614,23 +3709,28 @@ means to push this value onto the list in the variable.") (concat "\\<\\(" org-scheduled-string "\\|" org-deadline-string "\\|" org-closed-string + "\\|" org-archived-string "\\|" org-clock-string "\\)" " *[[<]\\([^]>]+\\)[]>]") org-keyword-time-not-clock-regexp (concat "\\<\\(" org-scheduled-string "\\|" org-deadline-string - "\\|" org-closed-string "\\)" + "\\|" org-closed-string + "\\|" org-archived-string + "\\)" " *[[<]\\([^]>]+\\)[]>]") org-maybe-keyword-time-regexp (concat "\\(\\<\\(" org-scheduled-string "\\|" org-deadline-string "\\|" org-closed-string + "\\|" org-archived-string "\\|" org-clock-string "\\)\\)?" " *\\([[<][0-9]\\{4\\}-[0-9]\\{2\\}-[0-9]\\{2\\} [^]\r\n>]*?[]>]\\|<%%([^\r\n>]*>\\)") org-planning-or-clock-line-re (concat "\\(?:^[ \t]*\\(" org-scheduled-string "\\|" org-deadline-string - "\\|" org-closed-string "\\|" org-clock-string "\\)\\>\\)") + "\\|" org-closed-string "\\|" org-clock-string + "\\|" org-archived-string "\\)\\>\\)") ) (org-set-font-lock-defaults))) @@ -4344,6 +4444,7 @@ between words." (list (concat "\\<" org-deadline-string) '(0 'org-special-keyword t)) (list (concat "\\<" org-scheduled-string) '(0 'org-special-keyword t)) (list (concat "\\<" org-closed-string) '(0 'org-special-keyword t)) + (list (concat "\\<" org-archived-string) '(0 'org-special-keyword t)) (list (concat "\\<" org-clock-string) '(0 'org-special-keyword t)) ;; Emphasis (if em @@ -4375,6 +4476,13 @@ between words." '("^[ \t]*\\(:.*\\)" (1 'org-table t)) '("| *\\(:?=[^|\n]*\\)" (1 'org-formula t)) '("^[ \t]*| *\\([#!$*_^]\\) *|" (1 'org-formula t)) + ;; Drawers + (list org-drawer-regexp '(0 'org-drawer t)) + (list "^[ \t]*:END:" '(0 'org-drawer t)) + ;; Properties + '("^[ \t]*\\(:[a-zA-Z0-9]+:\\)[ \t]*\\(\\S-.*\\)" + (1 'org-special-keyword t) (2 'org-property-value t)) +;FIXME (1 'org-tag t) (2 'org-property-value t)) (if org-format-transports-properties-p '("| *\\(<[0-9]+>\\) *" (1 'org-formula t))) '("^\\*+ \\(.*:ARCHIVE:.*\\)" (1 'org-archived prepend)) @@ -4476,14 +4584,6 @@ between words." (org-table-justify-field-maybe) (call-interactively 'org-table-next-field))))) - ((and org-drawers - (save-excursion - (beginning-of-line 1) - (looking-at org-drawer-regexp))) - ;; Toggle block visibility - (org-flag-drawer - (not (get-char-property (match-end 0) 'invisible)))) - ((eq arg t) ;; Global cycling (cond @@ -4512,6 +4612,14 @@ between words." (setq org-cycle-global-status 'overview) (run-hook-with-args 'org-cycle-hook 'overview)))) + ((and org-drawers + (save-excursion + (beginning-of-line 1) + (looking-at org-drawer-regexp))) + ;; Toggle block visibility + (org-flag-drawer + (not (get-char-property (match-end 0) 'invisible)))) + ((integerp arg) ;; Show-subtree, ARG levels up from here. (save-excursion @@ -5047,6 +5155,9 @@ in the region." ((eolp) (insert " ")) ((equal (char-after) ?\ ) (forward-char 1)))))) +(defun org-reduced-level (l) + (if org-odd-levels-only (1+ (floor (/ l 2))) l)) + (defun org-get-legal-level (level &optional change) "Rectify a level change under the influence of `org-odd-levels-only' LEVEL is a current level, CHANGE is by how much the level should be @@ -5530,7 +5641,6 @@ If WITH-CASE is non-nil, the sorting will be case-sensitive." ((= llt ?\)) "\\([ \t]*\\([-+]\\|\\([0-9]+)\\)\\)\\|[ \t]+\\*\\)\\( \\|$\\)") (t (error "Invalid value of `org-plain-list-ordered-item-terminator'"))))))) - (defun org-in-item-p () "It the cursor inside a plain list item. Does not have to be the first line." @@ -5625,7 +5735,9 @@ the whole buffer." (interactive "P") (save-excursion (let* ((buffer-invisibility-spec (org-inhibit-invisibility)) ; Emacs 21 - (beg (progn (outline-back-to-heading) (point))) + (beg (condition-case nil + (progn (outline-back-to-heading) (point)) + (error (point-min)))) (end (move-marker (make-marker) (progn (outline-next-heading) (point)))) (re "\\(\\[[0-9]*%\\]\\)\\|\\(\\[[0-9]*/[0-9]*\\]\\)") @@ -5894,6 +6006,33 @@ doing the renumbering." (org-maybe-renumber-ordered-list)) (error nil))) +(defun org-cycle-list-bullet (&optional which) + "Cycle through the different itemize/enumerate bullets. +This cycle the entire list level through the sequence: + + `-' -> `+' -> `*' -> `1.' -> `1)' + +If WHICH is a string, use that as the new bullet. If WHICH is an integer, +0 meand `-', 1 means `+' etc." + (interactive "P") + (org-preserve-lc + (org-beginning-of-item-list) + (org-at-item-p) + (beginning-of-line 1) + (let ((current (match-string 0)) new) + (setq new (cond + ((and which (nth (1- which) '("-" "+" "*" "1." "1)")))) + ((string-match "-" current) "+") + ((string-match "\\+" current) + (if (looking-at "\\S-") "1." "*")) + ((string-match "\\*" current) "1.") + ((string-match "\\." current) "1)") + ((string-match ")" current) "-") + (t (error "This should not happen")))) + (and (looking-at "\\([ \t]*\\)\\S-+") (replace-match (concat "\\1" new))) + (org-fix-bullet-type 1) + (org-maybe-renumber-ordered-list)))) + (defun org-get-string-indentation (s) "What indentation has S due to SPACE and TAB at the beginning of the string?" (let ((n -1) (i 0) (w tab-width) c) @@ -5943,16 +6082,13 @@ with something like \"1.\" or \"2)\"." (move-to-column col))) (defun org-fix-bullet-type (arg) - "Renumber an ordered plain list. -Cursor needs to be in the first line of an item, the line that starts -with something like \"1.\" or \"2)\"." + "Make sure all items in this list have the same bullet." (interactive "p") (unless (org-at-item-p) (error "This is not a list")) (let ((line (org-current-line)) (col (current-column)) (ind (current-indentation)) - ind1 (n (1- arg)) - bullet) + ind1 bullet) ;; find where this list begins (org-beginning-of-item-list) (beginning-of-line 1) @@ -5998,7 +6134,7 @@ I.e. to the first item in this list." (and (= ind1 ind) (not (org-at-item-p)))) (throw 'exit t) - (setq pos (point-at-bol)))))) + (when (org-at-item-p) (setq pos (point-at-bol))))))) (goto-char pos))) (defvar org-last-indent-begin-marker (make-marker)) @@ -6071,6 +6207,179 @@ I.e. to the first item in this list." (setq ind-down (current-column))))) (list ind ind-up ind-down))) +;;; The orgstruct minor mode + +;; Define a minor mode which can be used in other modes in order to +;; integrate the org-mode structure editing commands. + +;; This is really a hack, because the org-mode structure commands use +;; keys which normally belong to the major mode. Here is how it +;; works: The minor mode defines all the keys necessary to operate the +;; structure commands, but wraps the commands into a function which +;; tests if the cursor is currently at a headline or a plain list +;; item. If that is the case, the structure command is used, +;; temporarily setting many Org-mode variables like regular +;; expressions for filling etc. However, when any of those keys is +;; used at a different location, function uses `key-binding' to look +;; up if the key has an associated command in another currently active +;; keymap (minor modes, major mode, global), and executes that +;; command. There might be problems if any of the keys is otherwise +;; used as a prefix key. + +;; Another challenge is that the key binding for TAB can be tab or \C-i, +;; likewise the binding for RET can be return or \C-m. Orgtbl-mode +;; addresses this by checking explicitly for both bindings. + +(defvar orgstruct-mode-map (make-sparse-keymap) + "Keymap for the minor `org-cdlatex-mode'.") + +;;;###autoload +(define-minor-mode orgstruct-mode + "Toggle the minor more `orgstruct-mode'. +This mode is for using Org-mode structure commands in other modes. +The following key behave as if Org-mode was active, if the cursor +is on a headline, or on a plain list item (both in the definition +of Org-mode). + +M-up Move entry/item up +M-down Move entry/item down +M-left Promote +M-right Demote +M-S-up Move entry/item up +M-S-down Move entry/item down +M-S-left Promote subtree +M-S-right Demote subtree +M-q Fill paragraph and items like in Org-mode +C-c ^ Sort entries +C-c - Cycle list bullet +TAB Cycle item visibility +M-RET Insert new heading/item +S-M-RET Insert new TODO heading / Chekbox item +C-c C-c Set tags / toggle checkbox" + nil " OrgStruct" nil + (and (orgstruct-setup) (defun orgstruct-setup () nil))) + +;;;###autoload +(defun turn-on-orgstruct () + "Unconditionally turn on `orgstruct-mode'." + (orgstruct-mode 1)) + +(defun orgstruct-error () + "Error when there is no default binding for a structure key." + (interactive) + (error "This key is has no function outside structure elements")) + +(defvar org-local-vars nil + "List of local variables, for use by `orgstruct-mode'") + +(defun orgstruct-setup () + "Setup orgstruct keymaps." + (let ((nfunc 0) + (bindings + (list + '([(meta up)] org-metaup) + '([(meta down)] org-metadown) + '([(meta left)] org-metaleft) + '([(meta right)] org-metaright) + '([(meta shift up)] org-shiftmetaup) + '([(meta shift down)] org-shiftmetadown) + '([(meta shift left)] org-shiftmetaleft) + '([(meta shift right)] org-shiftmetaright) + '("\M-q" fill-paragraph) + '("\C-c^" org-sort) + '("\C-c-" org-cycle-list-bullet))) + elt key fun cmd) + (while (setq elt (pop bindings)) + (setq nfunc (1+ nfunc)) + (setq key (org-key (car elt)) + fun (nth 1 elt) + cmd (orgstruct-make-binding fun nfunc key)) + (org-defkey orgstruct-mode-map key cmd)) + + ;; Special treatment needed for TAB and RET + (org-defkey orgstruct-mode-map [(tab)] + (orgstruct-make-binding 'org-cycle 102 [(tab)] "\C-i")) + (org-defkey orgstruct-mode-map "\C-i" + (orgstruct-make-binding 'org-cycle 103 "\C-i" [(tab)])) + + (org-defkey orgstruct-mode-map "\M-\C-m" + (orgstruct-make-binding 'org-insert-heading 105 + "\M-\C-m" [(meta return)])) + (org-defkey orgstruct-mode-map [(meta return)] + (orgstruct-make-binding 'org-insert-heading 106 + [(meta return)] "\M-\C-m")) + + (org-defkey orgstruct-mode-map [(shift meta return)] + (orgstruct-make-binding 'org-insert-todo-heading 107 + [(meta return)] "\M-\C-m")) + + (org-defkey orgstruct-mode-map "\C-c\C-c" 'org-ctrl-c-ctrl-c) + (setq org-local-vars (org-get-local-variables)) + + t)) + +(defun orgstruct-make-binding (fun n &rest keys) + "Create a function for binding in the structure minor mode. +FUN is the command to call inside a table. N is used to create a unique +command name. KEYS are keys that should be checked in for a command +to execute outside of tables." + (eval + (list 'defun + (intern (concat "orgstruct-hijacker-command-" (int-to-string n))) + '(arg) + (concat "In Structure, run `" (symbol-name fun) "'.\n" + "Outside of structure, run the binding of `" + (mapconcat (lambda (x) (format "%s" x)) keys "' or `") + "'.") + '(interactive "p") + (list 'if + '(org-context-p 'headline 'item) + (list 'org-run-like-in-org-mode (list 'quote fun)) + (list 'let '(orgstruct-mode) + (list 'call-interactively + (append '(or) + (mapcar (lambda (k) + (list 'key-binding k)) + keys) + '('orgstruct-error)))))))) + +(defun org-context-p (&rest contexts) + "FIXME:" + (let ((pos (point))) + (goto-char (point-at-bol)) + (prog1 (or (and (memq 'table contexts) + (looking-at "[ \t]*|")) + (and (memq 'headline contexts) + (looking-at "\\*+")) + (and (memq 'item contexts) + (looking-at "[ \t]*\\([-+*] \\|[0-9]+[.)] \\)"))) + (goto-char pos)))) + +(defun org-get-local-variables () + "Return a list of all local variables in an org-mode buffer." + (let (varlist) + (with-current-buffer (get-buffer-create "*Org tmp*") + (erase-buffer) + (org-mode) + (setq varlist (buffer-local-variables))) + (kill-buffer "*Org tmp*") + (delq nil + (mapcar + (lambda (x) + (setq x + (if (symbolp x) + (list x) + (list (car x) (list 'quote (cdr x))))) + (if (string-match + "^\\(org-\\|orgtbl-\\|outline-\\|comment-\\|paragraph-\\|auto-fill\\|fill-paragraph\\|adaptive-fill\\|indent-\\)" + (symbol-name (car x))) + x nil)) + varlist)))) + +(defun org-run-like-in-org-mode (cmd) + (eval (list 'let org-local-vars + (list 'call-interactively (list 'quote cmd))))) + ;;;; Archiving (defalias 'org-advertized-archive-subtree 'org-archive-subtree) @@ -6178,15 +6487,16 @@ this heading." ;; Paste (org-paste-subtree (org-get-legal-level level 1)) ;; Mark the entry as done, i.e. set to last word in org-todo-keywords-1 FIXME: not right anymore!!!!!!! - (if org-archive-mark-done - (let (org-log-done) - (org-todo (length org-todo-keywords-1)))) + (when (and org-archive-mark-done + (looking-at org-todo-line-regexp) + (or (not (match-end 3)) + (not (member (match-string 3) org-done-keywords)))) + (let (org-log-done) + (org-todo (car org-done-keywords)))) + ;; Move cursor to right after the TODO keyword (when org-archive-stamp-time - (beginning-of-line 1) - (looking-at org-todo-line-regexp) - (goto-char (or (match-end 2) (match-beginning 3))) - (org-insert-time-stamp (org-current-time) t t "(" ")")) + (org-add-planning-info 'archived (org-current-time))) ;; Save the buffer, if it is not the same buffer. (if (not (eq this-buffer buffer)) (save-buffer)))) ;; Here we are back in the original buffer. Everything seems to have @@ -8020,7 +8330,7 @@ For all numbers larger than LIMIT, shift them by DELTA." (while (re-search-forward "^[ \t]*| *\\$ *\\(|.*\\)" end t) (setq fields (org-split-string (match-string 1) " *| *")) (while (setq field (pop fields)) - (if (string-match "^\\([a-zA-Z][a-zA-Z0-9]*\\|%\\) *= *\\(.*\\)" field) + (if (string-match "^\\([a-zA-Z][_a-zA-Z0-9]*\\|%\\) *= *\\(.*\\)" field) (push (cons (match-string 1 field) (match-string 2 field)) org-table-local-parameters)))) (goto-char beg) @@ -8354,6 +8664,12 @@ $1-> %s\n" orig formula form0 form)) (or suppress-align (and org-table-may-need-update (org-table-align)))))) +(defun org-table-put-field-property (prop value) + (save-excursion + (put-text-property (progn (skip-chars-backward "^|") (point)) + (progn (skip-chars-forward "^|") (point)) + prop value))) + (defun org-table-get-range (desc &optional tbeg col highlight) "Get a calc vector from a column, accorting to descriptor DESC. Optional arguments TBEG and COL can give the beginning of the table and @@ -8516,7 +8832,7 @@ With prefix arg ALL, do this for all lines in the table." (line-re org-table-dataline-regexp) (thisline (org-current-line)) (thiscol (org-table-current-column)) - beg end entry eqlnum eqlname eql (cnt 0) eq a name) + beg end entry eqlnum eqlname eqlname1 eql (cnt 0) eq a name) ;; Insert constants in all formulas (setq eqlist (mapcar (lambda (x) @@ -8546,6 +8862,30 @@ With prefix arg ALL, do this for all lines in the table." end (move-marker (make-marker) (1+ (point-at-eol))))) (goto-char beg) (and all (message "Re-applying formulas to full table...")) + + ;; First find the named fields, and mark them untouchanble + (remove-text-properties beg end '(org-untouchable t)) + (while (setq eq (pop eqlname)) + (setq name (car eq) + a (assoc name org-table-named-field-locations)) + (and (not a) + (string-match "@\\([0-9]+\\)\\$\\([0-9]+\\)" name) + (setq a (list name + (aref org-table-dlines + (string-to-number (match-string 1 name))) + (string-to-number (match-string 2 name))))) + (when (and a (or all (equal (nth 1 a) thisline))) + (message "Re-applying formula to field: %s" name) + (goto-line (nth 1 a)) + (org-table-goto-column (nth 2 a)) + (push (append a (list (cdr eq))) eqlname1) +;; FIXME (org-table-eval-formula nil (cdr eq) 'noalign 'nocst +;; FIXME 'nostore 'noanalysis) + (org-table-put-field-property :org-untouchable t))) + + ;; Now evauluate the column formulas, but skip fields covered by + ;; field formulas + (goto-char beg) (while (re-search-forward line-re end t) (unless (string-match "^ *[_^!$/] *$" (org-table-get-field 1)) ;; Unprotected line, recalculate @@ -8556,30 +8896,24 @@ With prefix arg ALL, do this for all lines in the table." (while (setq entry (pop eql)) (goto-line org-last-recalc-line) (org-table-goto-column (string-to-number (car entry)) nil 'force) - (org-table-eval-formula nil (cdr entry) - 'noalign 'nocst 'nostore 'noanalysis)))) + (unless (get-text-property (point) :org-untouchable) + (org-table-eval-formula nil (cdr entry) + 'noalign 'nocst 'nostore 'noanalysis))))) + + ;; Now evaluate the field formulas + (while (setq eq (pop eqlname1)) + (message "Re-applying formula to field: %s" (car eq)) + (goto-line (nth 1 eq)) + (org-table-goto-column (nth 2 eq)) + (org-table-eval-formula nil (nth 3 eq) 'noalign 'nocst + 'nostore 'noanalysis)) + (goto-line thisline) (org-table-goto-column thiscol) + (remove-text-properties (point-min) (point-max) '(org-untouchable t)) (or noalign (and org-table-may-need-update (org-table-align)) (and all (message "Re-applying formulas to %d lines...done" cnt))) - ;; Now do the named fields - (while (setq eq (pop eqlname)) - (setq name (car eq) - a (assoc name org-table-named-field-locations)) - (and (not a) - (string-match "@\\([0-9]+\\)\\$\\([0-9]+\\)" name) - (setq a - (list - name - (aref org-table-dlines - (string-to-number (match-string 1 name))) - (string-to-number (match-string 2 name))))) - (when (and a (or all (equal (nth 1 a) thisline))) - (message "Re-applying formula to field: %s" name) - (goto-line (nth 1 a)) - (org-table-goto-column (nth 2 a)) - (org-table-eval-formula nil (cdr eq) 'noalign 'nocst - 'nostore 'noanalysis))) + ;; back to initial position (message "Re-applying formulas...done") (goto-line thisline) @@ -8617,7 +8951,7 @@ With prefix arg ALL, do this for all lines in the table." (setq f (replace-match (concat "$" (cdr a)) t t f))) ;; Parameters and constants (setq start 0) - (while (setq start (string-match "\\$\\([a-zA-Z][a-zA-Z0-9]*\\)" f start)) + (while (setq start (string-match "\\$\\([a-zA-Z][_a-zA-Z0-9]*\\)" f start)) (setq start (1+ start)) (if (setq a (save-match-data (org-table-get-constant (match-string 1 f)))) @@ -8630,8 +8964,11 @@ With prefix arg ALL, do this for all lines in the table." "Find the value for a parameter or constant in a formula. Parameters get priority." (or (cdr (assoc const org-table-local-parameters)) + (cdr (assoc const org-table-formula-constants-local)) (cdr (assoc const org-table-formula-constants)) (and (fboundp 'constants-get) (constants-get const)) + (and (string= (substring const 0 (min 5 (length const))) "PROP_") + (org-entry-get nil (substring const 5) 'inherit)) "#UNDEFINED_NAME")) (defvar org-table-fedit-map (make-sparse-keymap)) @@ -9115,6 +9452,9 @@ With prefix ARG, apply the new formulas to the table." (t (cond ((not var) (error "No reference at point")) + ((setq e (assoc var org-table-formula-constants-local)) + (message "Local Constant: $%s=%s in #+CONSTANTS line." + var (cdr e))) ((setq e (assoc var org-table-formula-constants)) (message "Constant: $%s=%s in `org-table-formula-constants'." var (cdr e))) @@ -11492,21 +11832,34 @@ to be run from that hook to fucntion properly." (org-set-local 'org-remember-default-headline headline)) ;; Interactive template entries (goto-char (point-min)) - (while (re-search-forward "%^\\({\\([^}]*\\)}\\)?\\([uUtT]\\)?" nil t) + (while (re-search-forward "%^\\({\\([^}]*\\)}\\)?\\([guUtT]\\)?" nil t) (setq char (if (match-end 3) (match-string 3)) prompt (if (match-end 2) (match-string 2))) (goto-char (match-beginning 0)) (replace-match "") - (if char - (progn - (setq org-time-was-given (equal (upcase char) char)) - (setq time (org-read-date (equal (upcase char) "U") t nil - prompt)) - (org-insert-time-stamp time org-time-was-given - (member char '("u" "U")) - nil nil (list org-end-time-was-given))) + (cond + ((member char '("G" "g")) + (let* ((org-last-tags-completion-table + (org-global-tags-completion-table + (if (equal char "G") (org-agenda-files) (and file (list file))))) + (ins (completing-read + (if prompt (concat prompt ": ") "Tags: ") + 'org-tags-completion-function nil nil nil + 'org-tags-history))) + (insert (concat ":" (mapconcat 'identity + (org-split-string ins (org-re "[^[:alnum:]]+")) + ":") + ":")))) + (char + (setq org-time-was-given (equal (upcase char) char)) + (setq time (org-read-date (equal (upcase char) "U") t nil + prompt)) + (org-insert-time-stamp time org-time-was-given + (member char '("u" "U")) + nil nil (list org-end-time-was-given))) + (t (insert (read-string - (if prompt (concat prompt ": ") "Enter string"))))) + (if prompt (concat prompt ": ") "Enter string")))))) (goto-char (point-min)) (if (re-search-forward "%\\?" nil t) (replace-match "") @@ -11815,7 +12168,10 @@ At all other locations, this simply calls `ispell-complete-word'." (point))) (confirm (lambda (x) (stringp (car x)))) (searchhead (equal (char-before beg) ?*)) - (tag (equal (char-before beg1) ?:)) + (tag (and (equal (char-before beg1) ?:) + (equal (char-after (point-at-bol)) ?*))) + (prop (and (equal (char-before beg1) ?:) + (not (equal (char-after (point-at-bol)) ?*)))) (texp (equal (char-before beg) ?\\)) (link (equal (char-before beg) ?\[)) (opt (equal (buffer-substring (max (point-at-bol) (- beg 2)) @@ -11857,6 +12213,8 @@ At all other locations, this simply calls `ispell-complete-word'." tbl) (tag (setq type :tag beg beg1) (or org-tag-alist (org-get-buffer-tags))) + (prop (setq type :prop beg beg1) + (mapcar 'list (org-buffer-property-keys))) (t (progn (ispell-complete-word arg) (throw 'exit nil))))) (pattern (buffer-substring-no-properties beg end)) (completion (try-completion pattern table confirm))) @@ -11864,7 +12222,7 @@ At all other locations, this simply calls `ispell-complete-word'." (if (equal type :opt) (insert (substring (cdr (assoc (upcase pattern) table)) (length pattern))) - (if (equal type :tag) (insert ":")))) + (if (memq type '(:tag :prop)) (insert ":")))) ((null completion) (message "Can't find completion for \"%s\"" pattern) (ding)) @@ -11877,7 +12235,7 @@ At all other locations, this simply calls `ispell-complete-word'." (delete-window (get-buffer-window "*Completions*"))) (if (assoc completion table) (if (eq type :todo) (insert " ") - (if (eq type :tag) (insert ":")))) + (if (memq type '(:tag :prop)) (insert ":")))) (if (and (equal type :opt) (assoc completion table)) (message "%s" (substitute-command-keys "Press \\[org-complete] again to insert example settings")))) @@ -12207,7 +12565,8 @@ be removed." (if (not (equal (char-before) ?\ )) " " "") (cond ((eq what 'scheduled) org-scheduled-string) ((eq what 'deadline) org-deadline-string) - ((eq what 'closed) org-closed-string)) + ((eq what 'closed) org-closed-string) + ((eq what 'archived) org-archived-string)) " ") (org-insert-time-stamp time @@ -12471,6 +12830,7 @@ ACTION can be `set', `up', `down', or a character." (insert " [#" news "]")) (goto-char (match-beginning 3)) (insert "[#" news "] "))))) + (org-preserve-lc (org-set-tags nil 'align)) (if remove (message "Priority removed") (message "Priority of current item set to %s" news)))) @@ -12518,7 +12878,7 @@ are included in the output." (setq todo (if (match-end 1) (match-string 2)) tags (if (match-end 4) (match-string 4))) (goto-char (setq lspos (1+ (match-beginning 0)))) - (setq level (funcall outline-level) + (setq level (org-reduced-level (funcall outline-level)) category (org-get-category)) (setq i llast llast level) ;; remove tag lists from same and sublevels @@ -12577,25 +12937,43 @@ also TODO lines." (interactive "P") (org-scan-tags 'sparse-tree (cdr (org-make-tags-matcher match)) todo-only)) +(defvar org-cached-props nil) +(defun org-cached-entry-get (pom property) + (cdr (assoc property (or org-cached-props + (setq org-cached-props + (org-entry-properties pom)))))) + +(defun org-global-tags-completion-table (&optional files) + "Return the list of all tags in all agenda buffer/files." + (save-excursion + (org-uniquify + (apply 'append + (mapcar + (lambda (file) + (set-buffer (find-file-noselect file)) + (org-get-buffer-tags)) + (if (and files (car files)) + files + (org-agenda-files))))))) + (defun org-make-tags-matcher (match) "Create the TAGS//TODO matcher form for the selection string MATCH." ;; todo-only is scoped dynamically into this function, and the function ;; may change it it the matcher asksk for it. (unless match ;; Get a new match request, with completion - (setq org-last-tags-completion-table - (or org-tag-alist - org-last-tags-completion-table)) - (setq match (completing-read - "Match: " 'org-tags-completion-function nil nil nil - 'org-tags-history))) - + (let ((org-last-tags-completion-table + (org-global-tags-completion-table))) + (setq match (completing-read + "Match: " 'org-tags-completion-function nil nil nil + 'org-tags-history)))) + ;; Parse the string and create a lisp form (let ((match0 match) - (re (org-re "^&?\\([-+:]\\)?\\({[^}]+}\\|LEVEL=\\([0-9]+\\)\\|[[:alnum:]_@]+\\)")) + (re (org-re "^&?\\([-+:]\\)?\\({[^}]+}\\|LEVEL=\\([0-9]+\\)\\|\\([[:alnum:]]+\\)=\\({[^}]+}\\|\"[^\"]+\"\\)\\|[[:alnum:]_@]+\\)")) minus tag mm tagsmatch todomatch tagsmatcher todomatcher kwd matcher - orterms term orlist re-p level-p) + orterms term orlist re-p level-p prop-p pn pv) (if (string-match "/+" match) ;; match contains also a todo-matching request (progn @@ -12621,10 +12999,19 @@ also TODO lines." tag (match-string 2 term) re-p (equal (string-to-char tag) ?{) level-p (match-end 3) + prop-p (match-end 4) mm (cond (re-p `(org-match-any-p ,(substring tag 1 -1) tags-list)) (level-p `(= level ,(string-to-number (match-string 3 term)))) + (prop-p + (setq pn (match-string 4 term) + pv (match-string 5 term) + re-p (equal (string-to-char pv) ?{) + pv (substring pv 1 -1)) + (if re-p + `(string-match ,pv (org-cached-entry-get nil ,pn)) + `(equal ,pv (org-cached-entry-get nil ,pn)))) (t `(member ,(downcase tag) tags-list))) mm (if minus (list 'not mm) mm) term (substring term (match-end 0))) @@ -12634,7 +13021,9 @@ also TODO lines." (car tagsmatcher)) orlist) (setq tagsmatcher nil)) - (setq tagsmatcher (if (> (length orlist) 1) (cons 'or orlist) (car orlist)))) + (setq tagsmatcher (if (> (length orlist) 1) (cons 'or orlist) (car orlist))) + (setq tagsmatcher + (list 'progn '(setq org-cached-props nil) tagsmatcher))) ;; Make the todo matcher (if (or (not todomatch) (not (string-match "\\S-" todomatch))) @@ -12980,10 +13369,529 @@ Returns the new tags string, or nil to not change the current settings." (goto-char (point-min)) (while (re-search-forward (org-re "[ \t]:\\([[:alnum:]_@:]+\\):[ \t\r\n]") nil t) - (mapc (lambda (x) (add-to-list 'tags x)) - (org-split-string (org-match-string-no-properties 1) ":")))) + (when (equal (char-after (point-at-bol 0)) ?*) + (mapc (lambda (x) (add-to-list 'tags x)) + (org-split-string (org-match-string-no-properties 1) ":"))))) (mapcar 'list tags))) + +;;;; Properties + +;;; Setting and retrieving properties + +(defconst org-special-properties + '("TODO" "TAGS" "ALLTAGS" "DEADLINE" "SCHEDULED" + "CLOCK" "PRIORITY") + "The special properties valid in Org-mode. + +These are properties that are not defined in the property drawer, +but in some other way.") + +(defconst org-property-start-re "^[ \t]*:PROPERTIES:[ \t]*$" + "Regular expression matching the first line of a property drawer.") + +(defconst org-property-end-re "^[ \t]*:END:[ \t]*$" + "Regular expression matching the first line of a property drawer.") + +(defmacro org-with-point-at (pom &rest body) + "Move to buffer and point of point-or-marker POM for the duration of BODY." + (declare (indent 1) (debug t)) + `(save-excursion + (if (markerp pom) (set-buffer (marker-buffer pom))) + (save-excursion + (goto-char (or pom (point))) + ,@body))) + +(defun org-get-property-block (&optional beg end force) + "Return the (beg . end) range of the body of the property drawer. +BEG and END can be beginning and end of subtree, if not given +they will be found. +If the drawer does not exist and FORCE is non-nil, greater the drawer." + (catch 'exit + (save-excursion + (let* ((beg (or beg (progn (org-back-to-heading t) (point)))) + (end (or end (progn (outline-next-heading) (point))))) + (goto-char beg) + (if (re-search-forward org-property-start-re end t) + (setq beg (1+ (match-end 0))) + (or force (throw 'exit nil)) + (beginning-of-line 2) + (while (and (looking-at (concat "[ \t]*" org-keyword-time-regexp)) + (not (equal (match-string 1) org-clock-string))) + (beginning-of-line 2)) + (insert ":PROPERTIES:\n:END:\n") + (beginning-of-line -1) + (org-indent-line-function) + (setq beg (1+ (point-at-eol)) end beg) + (beginning-of-line 2) + (org-indent-line-function) + (throw 'exit (cons beg end))) + (if (re-search-forward org-property-end-re end t) + (setq end (match-beginning 0)) + (or force (throw 'exit nil)) + (goto-char beg) + (setq end beg) + (org-indent-line-function) + (insert ":END:\n")) + (cons beg end))))) + +(defun org-entry-properties (&optional pom which) + "Get all properties of the entry at point-or-marker POM. +This includes the TODO keyword, the tags, time strings for deadline, +scheduled, and clocking, and any additional properties defined in the +entry. The return value is an alist, keys may occur multiple times +if the property key was used several times. +POM may also be nil, in which case the current entry is used. +If WHICH is nil or `all', get all properties. If WHICH is +`special' or `standard', only get that subclass." + (setq which (or which 'all)) + (org-with-point-at pom + (let ((clockstr (substring org-clock-string 0 -1)) + (excluded '("TODO" "TAGS" "ALLTAGS" "PRIORITY")) + beg end range props key value) + (save-excursion + (when (condition-case nil (org-back-to-heading t) (error nil)) + (setq beg (point)) + (outline-next-heading) + (setq end (point)) + (when (memq which '(all special)) + ;; Get the special properties, like TODO and tags + (goto-char beg) + (when (and (looking-at org-todo-line-regexp) (match-end 2)) + (push (cons "TODO" (org-match-string-no-properties 2)) props)) + (when (looking-at org-priority-regexp) + (push (cons "PRIORITY" (org-match-string-no-properties 2)) props)) + (when (and (setq value (org-get-tags)) (string-match "\\S-" value)) + (push (cons "TAGS" value) props)) + (when (setq value (org-get-tags-at)) + (push (cons "ALLTAGS" (concat ":" (mapconcat 'identity value ":") ":")) + props)) + (while (re-search-forward org-keyword-time-regexp end t) + (setq key (substring (org-match-string-no-properties 1) 0 -1)) + (unless (member key excluded) (push key excluded)) + (push (cons key + (if (equal key clockstr) + (org-no-properties + (org-trim + (buffer-substring + (match-beginning 2) (point-at-eol)))) + (org-match-string-no-properties 2))) + props))) + (when (memq which '(all standard)) + ;; Get the standard properties, like :PORP: ... + (setq range (org-get-property-block beg end)) + (when range + (goto-char (car range)) + (while (re-search-forward + "^[ \t]*:\\([a-zA-Z][a-zA-Z0-9]*\\):[ \t]*\\(\\S-.*\\S-\\)" + (cdr range) t) + (setq key (org-match-string-no-properties 1) + value (org-match-string-no-properties 2)) + (unless (member key excluded) + (push (cons key value) props))))) + (nreverse props)))))) + +(defun org-entry-get (pom property &optional inherit) + "Get value of PROPERTY for entry at point-or-marker POM. +If INHERIT is non-nil and the entry does not have the property, +then also check higher levels of the hierarchy." + (org-with-point-at pom + (if inherit + (org-entry-get-with-inheritance property) + (if (member property org-special-properties) + ;; We need a special property. Use brute force, get all properties. + (cdr (assoc property (org-entry-properties nil 'special))) + (let ((range (org-get-property-block))) + (if (and range + (goto-char (car range)) + (re-search-forward + (concat "^[ \t]*:" property ":[ \t]*\\(.*\\S-\\)") + (cdr range) t)) + ;; Found the property, return it. + (org-match-string-no-properties 1))))))) + +(defun org-entry-delete (pom property) + "Delete the property PROPERTY from entry at point-or-marker POM." + (org-with-point-at pom + (if (member property org-special-properties) + nil ; cannot delete these properties. + (let ((range (org-get-property-block))) + (if (and range + (goto-char (car range)) + (re-search-forward + (concat "^[ \t]*:" property ":[ \t]*\\(.*\\S-\\)") + (cdr range) t)) + (delete-region (match-beginning 0) (1+ (point-at-eol)))))))) + +(defvar org-entry-property-inherited-from (make-marker)) + +(defun org-entry-get-with-inheritance (property) + "Get entry property, and search higher levels if not present." + (let (tmp) + (save-excursion + (catch 'ex + (while t + (when (setq tmp (org-entry-get nil property)) + (org-back-to-heading t) + (move-marker org-entry-property-inherited-from (point)) + (throw 'ex tmp)) + (condition-case nil + (org-up-heading-all 1) + (error (throw 'ex nil)))))))) + +(defun org-entry-put (pom property value) + "Set PROPERTY to VALUE for entry at point-or-marker POM." + (org-with-point-at pom + (org-back-to-heading t) + (let ((beg (point)) (end (save-excursion (outline-next-heading) (point))) + range) + (cond + ((equal property "TODO") + (when (and (stringp value) (string-match "\\S-" value) + (not (member value org-todo-keywords-1))) + (error "\"%s\" is not a valid TODO state" value)) + (if (or (not value) + (not (string-match "\\S-" value))) + (setq value 'none)) + (org-todo value) + (org-set-tags nil 'align)) + ((equal property "PRIORITY") + (org-priority (if (and value (stringp value) (string-match "\\S-" value)) + (string-to-char value) ?\ )) + (org-set-tags nil 'align)) + ((member property org-special-properties) + (error "The %s property can not yet be set with `org-entry-put'" + property)) + (t ; a non-special property + (setq range (org-get-property-block beg end 'force)) + (goto-char (car range)) + (if (re-search-forward + (concat "^[ \t]*:" property ":\\(.*\\)") (cdr range) t) + (progn + (delete-region (match-beginning 1) (match-end 1)) + (goto-char (match-beginning 1))) + (goto-char (cdr range)) + (insert "\n") + (backward-char 1) + (org-indent-line-function) + (insert ":" property ":")) + (and value (insert " " value))))))) + +(defun org-buffer-property-keys (&optional include-specials) + "Get all property keys in the current buffer." + (let (rtn range) + (save-excursion + (save-restriction + (widen) + (goto-char (point-min)) + (while (re-search-forward org-property-start-re nil t) + (setq range (org-get-property-block)) + (goto-char (car range)) + (while (re-search-forward "^[ \t]*:\\([a-zA-Z0-9]+\\):" (cdr range) t) + (add-to-list 'rtn (org-match-string-no-properties 1))) + (outline-next-heading)))) + (when include-specials + (setq rtn (append org-special-properties rtn))) + (sort rtn (lambda (a b) (string< (upcase a) (upcase b)))))) + +;; FIXME: This should automatically find the right place int he entry. +;; And then org-entry-put should use it. +(defun org-insert-property-drawer () + "Insert a property drawer at point." + (interactive) + (beginning-of-line 1) + (insert ":PROPERTIES:\n:END:\n") + (beginning-of-line -1) + (org-indent-line-function) + (beginning-of-line 2) + (org-indent-line-function) + (end-of-line 0)) + +(defvar org-column-overlays nil + "Holds the list of current column overlays.") + +(defvar org-current-columns-fmt nil + "Loval variable, holds the currently active column format.") +(defvar org-current-columns-maxwidths nil + "Loval variable, holds the currently active maximum column widths.") + +(defvar org-column-map (make-sparse-keymap) + "The keymap valid in column display.") + +(define-key org-column-map "e" 'org-column-edit) +(define-key org-column-map "v" 'org-column-show-value) +(define-key org-column-map "q" 'org-column-quit) +(define-key org-column-map [left] 'backward-char) +(define-key org-column-map [right] 'forward-char) + +(easy-menu-define org-column-menu org-column-map "Org Column Menu" + '("Column" + ["Edit property" org-column-edit t] + ["Show full value" org-column-show-value t] + ["Quit" org-column-quit t])) + +(defun org-new-column-overlay (beg end &optional string face) + "Create a new column overlay an add it to the list." + (let ((ov (org-make-overlay beg end))) + (org-overlay-put ov 'face (or face 'secondary-selection)) + (org-overlay-display ov string face) + (push ov org-column-overlays) + ov)) + +(defun org-overlay-columns (&optional props) + "Overlay the current line with column display." + (interactive) + (let ((fmt (copy-sequence org-current-columns-fmt)) + (beg (point-at-bol)) + (start 0) props pom property ass width f string ov) + ;; Check if the entry is in another buffer. + (unless props + (if (eq major-mode 'org-agenda-mode) + (setq pom (or (get-text-property (point) 'org-hd-marker) + (get-text-property (point) 'org-marker)) + props (if pom (org-entry-properties pom) nil)) + (setq props (org-entry-properties nil)))) + ;; Parse the format + (while (string-match "%\\([0-9]+\\)?\\([a-zA-Z0-9]+\\)\\-*" + fmt start) + (setq start (match-end 0) + property (match-string 2 fmt) + ass (if (equal property "ITEM") + (cons "ITEM" + (save-match-data + (org-no-properties + (org-remove-tabs + (buffer-substring-no-properties + (point-at-bol) (point-at-eol)))))) + (assoc property props)) + width (or (cdr (assoc property org-current-columns-maxwidths)) + (string-to-number (or (match-string 1 fmt) "10"))) + f (format "%%-%d.%ds | " width width) + string (format f (or (cdr ass) ""))) + ;; Create the overlay + (org-unmodified + (setq ov (org-new-column-overlay + beg (setq beg (1+ beg)) string 'org-column)) + (org-overlay-put ov 'keymap org-column-map) + (org-overlay-put ov 'org-column-key property) + (org-overlay-put ov 'org-column-value (cdr ass))) + (if (or (not (char-after beg)) + (equal (char-after beg) ?\n)) + (let ((inhibit-read-only t)) + (save-excursion + (goto-char beg) + (insert " "))))) + ;; Make the rest of the line disappear. + ;; FIXME: put the keymap also at the end of the line! + (org-unmodified + (setq ov (org-new-column-overlay beg (point-at-eol))) + (org-overlay-put ov 'invisible t) + (org-overlay-put ov 'keymap 'org-column-map) + (push ov org-column-overlays) + (setq ov (org-make-overlay (1- (point-at-eol)) (1+ (point-at-eol)))) + (org-overlay-put ov 'keymap 'org-column-map) + (push ov org-column-overlays) + (let ((inhibit-read-only t)) + (put-text-property (1- (point-at-bol)) + (min (point-max) (1+ (point-at-eol))) + 'read-only "Type `e' to edit property"))))) + +(defun org-overlay-columns-title () + "Overlay the newline before the current line with the table title." + (interactive) + (let ((fmt (copy-sequence org-current-columns-fmt)) + (start 0) + string (title "") + property width f ov) + (while (string-match "%\\([0-9]+\\)?\\([a-zA-Z0-9]+\\)\\-*" + fmt start) + (setq start (match-end 0) + property (match-string 2 fmt) + width (or (cdr (assoc property org-current-columns-maxwidths)) + (string-to-number (or (match-string 1 fmt) "10"))) + f (format "%%-%d.%ds | " width width) + string (format f property) + title (concat title string))) + (org-unmodified + (setq ov (org-new-column-overlay + (1- (point-at-bol)) (point-at-bol) + (concat "\n" (make-string (length title) ?-) "\n" + title "\n" (make-string (length title) ?-) "\n") + 'bold)) + (org-overlay-put ov 'keymap org-column-map)))) + +(defun org-remove-column-overlays () + "Remove all currently active column overlays." + (interactive) + (org-unmodified + (mapc 'org-delete-overlay org-column-overlays) + (setq org-column-overlays nil) + (let ((inhibit-read-only t)) + (remove-text-properties (point-min) (point-max) '(read-only t))))) + +(defun org-column-show-value () + "Show the full value of the property." + (interactive) + (let ((value (get-char-property (point) 'org-column-value))) + (message "Value is: %s" (or value "")))) + +(defun org-column-quit () + "Remove the column overlays and in this way exit column editing." + (interactive) + (org-unmodified + (org-remove-column-overlays) + (let ((inhibit-read-only t)) + ;; FIXME: is this safe??? + ;; or are there other reasons why there may be a read-only property???? + (remove-text-properties (point-min) (point-max) '(read-only t)))) + (when (eq major-mode 'org-agenda-mode) + (message "Modification not yet reflected in Agenda buffer, use `r' to refresh"))) + +(defun org-column-edit () + "Edit the value of the property at point in column view. +Where possible, use the standard interface for changing this line." + (interactive) + (let* ((col (current-column)) + (key (get-char-property (point) 'org-column-key)) + (value (get-char-property (point) 'org-column-value)) + (bol (point-at-bol)) (eol (point-at-eol)) + (pom (or (get-text-property bol 'org-hd-marker) + (point))) ; keep despite of compiler waring + (line-overlays + (delq nil (mapcar (lambda (x) + (and (eq (overlay-buffer x) (current-buffer)) + (>= (overlay-start x) bol) + (<= (overlay-start x) eol) + x)) + org-column-overlays))) + nval eval) + (when (equal key "ITEM") + (error "Cannot edit item headline from here")) + + (cond + ((equal key "TODO") + (setq eval '(org-with-point-at pom + (let ((current-prefix-arg '(4))) (org-todo '(4)))))) + ((equal key "PRIORITY") + (setq eval '(org-with-point-at pom + (call-interactively 'org-priority)))) + ((equal key "TAGS") + (setq eval '(org-with-point-at pom + (let ((org-fast-tag-selection-single-key + (if (eq org-fast-tag-selection-single-key 'expert) + t org-fast-tag-selection-single-key))) + (call-interactively 'org-set-tags))))) + ((equal key "DEADLINE") + (setq eval '(org-with-point-at pom + (call-interactively 'org-deadline)))) + ((equal key "SCHEDULED") + (setq eval '(org-with-point-at pom + (call-interactively 'org-deadline)))) + (t + (setq nval (read-string "Edit: " value)) + (setq nval (org-trim nval)) + (when (not (equal nval value)) + (setq eval '(org-entry-put pom key nval))))) + (when eval + (let ((inhibit-read-only t)) + (remove-text-properties (1- bol) eol '(read-only t)) + (unwind-protect + (progn + (setq org-column-overlays + (org-delete-all line-overlays org-column-overlays)) + (mapc 'org-delete-overlay line-overlays) + (eval eval)) + (org-overlay-columns)))) + (move-to-column col))) + +(defun org-columns () + "Turn on column view on an org-mode file." + (interactive) + (org-remove-column-overlays) + (let (beg end fmt cache maxwidths) + (move-marker org-entry-property-inherited-from nil) + (setq fmt (org-entry-get nil "COLUMNS" t)) + (unless fmt + (message "No local columns format defined, using default")) + (org-set-local 'org-current-columns-fmt (or fmt org-default-columns-format)) + (org-back-to-heading) + (save-excursion + (if (marker-position org-entry-property-inherited-from) + (goto-char org-entry-property-inherited-from)) + (setq beg (point) + end (org-end-of-subtree t t)) + (goto-char beg) + ;; Get and cache the properties + (while (re-search-forward (concat "^" outline-regexp) end t) + (push (cons (org-current-line) (org-entry-properties)) cache)) + (when cache + (setq maxwidths (org-get-columns-autowidth-alist fmt cache)) + (org-set-local 'org-current-columns-maxwidths maxwidths) + (goto-line (car (org-last cache))) + (org-overlay-columns-title) + (mapc (lambda (x) + (goto-line (car x)) + (org-overlay-columns (cdr x))) + cache))))) + +(defvar org-overriding-columns-format nil + "FIXME:") +(defvar org-agenda-view-columns-initially nil + "FIXME:") + +(defun org-agenda-columns () + "Turn on column view in the agenda." + (interactive) + (let (fmt first-done cache maxwidths m) + (cond + ((and (local-variable-p 'org-overriding-columns-format) + org-overriding-columns-format) + (setq fmt org-overriding-columns-format)) + ((setq m (get-text-property (point-at-bol) 'org-hd-marker)) + (setq fmt (org-entry-get m "COLUMNS" t))) + ((and (boundp 'org-current-columns-fmt) + (local-variable-p 'org-current-columns-fmt) + org-current-columns-fmt) + (setq fmt org-current-columns-fmt)) + ((setq m (next-single-property-change (point-min) 'org-hd-marker)) + (setq m (get-text-property m 'org-hd-marker)) + (setq fmt (org-entry-get m "COLUMNS" t)))) + (setq fmt (or fmt org-default-columns-format)) + (org-set-local 'org-current-columns-fmt fmt) + (save-excursion + ;; Get and cache the properties + (goto-char (point-min)) + (while (not (eobp)) + (when (setq m (or (get-text-property (point) 'org-hd-marker) + (get-text-property (point) 'org-marker))) + (push (cons (org-current-line) (org-entry-properties m)) cache)) + (beginning-of-line 2)) + (when cache + (setq maxwidths (org-get-columns-autowidth-alist fmt cache)) + (org-set-local 'org-current-columns-maxwidths maxwidths) + (goto-line (car (org-last cache))) + (org-overlay-columns-title) + (mapc (lambda (x) + (goto-line (car x)) + (org-overlay-columns (cdr x))) + cache))))) + +(defun org-get-columns-autowidth-alist (s cache) + "Derive the maximum column widths from the format and the cache." + (let ((start 0) rtn) + (while (string-match "%\\([a-zA-Z]\\S-*\\)" s start) + (push (cons (match-string 1 s) 1) rtn) + (setq start (match-end 0))) + (mapc (lambda (x) + (setcdr x (apply 'max + (mapcar + (lambda (y) + (length (or (cdr (assoc (car x) (cdr y))) " "))) + cache)))) + rtn) + rtn)) + + ;;;; Timestamps (defvar org-last-changed-timestamp nil) @@ -14347,6 +15255,8 @@ The following commands are available: (org-defkey org-agenda-mode-map "." 'org-agenda-goto-today) (org-defkey org-agenda-mode-map "d" 'org-agenda-day-view) (org-defkey org-agenda-mode-map "w" 'org-agenda-week-view) +(org-defkey org-agenda-mode-map "m" 'org-agenda-month-view) +(org-defkey org-agenda-mode-map "y" 'org-agenda-year-view) (org-defkey org-agenda-mode-map [(shift right)] 'org-agenda-date-later) (org-defkey org-agenda-mode-map [(shift left)] 'org-agenda-date-earlier) (org-defkey org-agenda-mode-map [?\C-c ?\C-x (right)] 'org-agenda-date-later) @@ -14382,7 +15292,6 @@ The following commands are available: '(org-defkey calendar-mode-map org-calendar-to-agenda-key 'org-calendar-goto-agenda)) (org-defkey org-agenda-mode-map "C" 'org-agenda-convert-date) -(org-defkey org-agenda-mode-map "m" 'org-agenda-phases-of-moon) (org-defkey org-agenda-mode-map "M" 'org-agenda-phases-of-moon) (org-defkey org-agenda-mode-map "S" 'org-agenda-sunrise-sunset) (org-defkey org-agenda-mode-map "h" 'org-agenda-holidays) @@ -14398,7 +15307,9 @@ The following commands are available: (org-defkey org-agenda-mode-map [?\C-c ?\C-x (down)] 'org-agenda-priority-down) (org-defkey org-agenda-mode-map [(right)] 'org-agenda-later) (org-defkey org-agenda-mode-map [(left)] 'org-agenda-earlier) -(org-defkey org-agenda-mode-map "\C-c\C-x\C-c" 'org-export-icalendar-combine-agenda-files) +(org-defkey org-agenda-mode-map "\C-c\C-x\C-c" 'org-agenda-columns) +; FIXME: other key? wtah about the menu???/ +;(org-defkey org-agenda-mode-map "\C-c\C-x\C-c" 'org-export-icalendar-combine-agenda-files) (defvar org-agenda-keymap (copy-keymap org-agenda-mode-map) "Local keymap for agenda entries from Org-mode.") @@ -14427,16 +15338,18 @@ The following commands are available: ["Next Dates" org-agenda-later (org-agenda-check-type nil 'agenda)] ["Previous Dates" org-agenda-earlier (org-agenda-check-type nil 'agenda)] "--" - ("Tags" + ("Tags and Properties" ["Show all Tags" org-agenda-show-tags t] - ["Set Tags" org-agenda-set-tags t]) + ["Set Tags" org-agenda-set-tags t] + "--" + ["Column View" org-columns t]) ("Date/Schedule" ["Schedule" org-agenda-schedule t] ["Set Deadline" org-agenda-deadline t] "--" - ["Change date +1 day" org-agenda-date-later (org-agenda-check-type nil 'agenda 'timeline)] - ["Change date -1 day" org-agenda-date-earlier (org-agenda-check-type nil 'agenda 'timeline)] - ["Change date to ..." org-agenda-date-prompt (org-agenda-check-type nil 'agenda 'timeline)]) + ["Change Date +1 day" org-agenda-date-later (org-agenda-check-type nil 'agenda 'timeline)] + ["Change Date -1 day" org-agenda-date-earlier (org-agenda-check-type nil 'agenda 'timeline)] + ["Change Date to ..." org-agenda-date-prompt (org-agenda-check-type nil 'agenda 'timeline)]) ("Priority" ["Set Priority" org-agenda-priority t] ["Increase Priority" org-agenda-priority-up t] @@ -14457,6 +15370,10 @@ The following commands are available: :style radio :selected (equal org-agenda-ndays 1)] ["Week View" org-agenda-week-view :active (org-agenda-check-type nil 'agenda) :style radio :selected (equal org-agenda-ndays 7)] + ["Month View" org-agenda-month-view :active (org-agenda-check-type nil 'agenda) + :style radio :selected (member org-agenda-ndays '(28 29 30 31))] + ["Year View" org-agenda-year-view :active (org-agenda-check-type nil 'agenda) + :style radio :selected (member org-agenda-ndays '(365 366))] "--" ["Show Logbook entries" org-agenda-log-mode :style toggle :selected org-agenda-show-log :active (org-agenda-check-type nil 'agenda 'timeline)] @@ -14491,11 +15408,6 @@ The following commands are available: `(unless (get-text-property (point) 'org-protected) ,@body)) -(defmacro org-unmodified (&rest body) - "Execute body without changing buffer-modified-p." - `(set-buffer-modified-p - (prog1 (buffer-modified-p) ,@body))) - (defmacro org-with-remote-undo (_buffer &rest _body) "Execute BODY while recording undo information in two buffers." (declare (indent 1) (debug t)) @@ -15171,15 +16083,22 @@ Optional argument FILE means, use this file instead of the current." (defun org-finalize-agenda () "Finishing touch for the agenda buffer, called just before displaying it." (unless org-agenda-multi - (org-agenda-align-tags) (save-excursion (let ((buffer-read-only)) (goto-char (point-min)) (while (org-activate-bracket-links (point-max)) (add-text-properties (match-beginning 0) (match-end 0) '(face org-link))) + (org-agenda-align-tags) (unless org-agenda-with-colors (remove-text-properties (point-min) (point-max) '(face nil)))) + (if (and (boundp 'org-overriding-columns-format) + org-overriding-columns-format) + (org-set-local 'org-overriding-columns-format + org-overriding-columns-format)) + (if (and (boundp 'org-agenda-view-columns-initially) + org-agenda-view-columns-initially) + (org-agenda-columns)) (run-hooks 'org-finalize-agenda-hook)))) (defun org-prepare-agenda-buffers (files) @@ -15456,6 +16375,7 @@ When EMPTY is non-nil, also include days without any entries." (defvar org-agenda-last-arguments nil "The arguments of the previous call to org-agenda") (defvar org-starting-day nil) ; local variable in the agenda buffer +(defvar org-agenda-span nil) ; local variable in the agenda buffer (defvar org-include-all-loc nil) ; local variable @@ -15487,9 +16407,8 @@ NDAYS defaults to `org-agenda-ndays'." (org-set-sorting-strategy 'agenda) (require 'calendar) (let* ((org-agenda-start-on-weekday - (if (or (equal ndays 1) - (and (null ndays) (equal 1 org-agenda-ndays))) - nil org-agenda-start-on-weekday)) + (if (or (equal ndays 7) (and (null ndays) (equal 7 org-agenda-ndays))) + org-agenda-start-on-weekday nil)) (thefiles (org-agenda-files)) (files thefiles) (today (time-to-days (current-time))) @@ -15517,6 +16436,8 @@ NDAYS defaults to `org-agenda-ndays'." (org-prepare-agenda "Day/Week") (org-set-local 'org-starting-day (car day-numbers)) (org-set-local 'org-include-all-loc include-all) + (org-set-local 'org-agenda-span + (org-agenda-ndays-to-span nd)) (when (and (or include-all org-agenda-include-all-todo) (member today day-numbers)) (setq files thefiles @@ -15534,7 +16455,8 @@ NDAYS defaults to `org-agenda-ndays'." (list 'face 'org-agenda-structure)) (insert (org-finalize-agenda-entries rtnall) "\n"))) (setq s (point)) - (insert (if (= nd 7) "Week-" "Day-") "agenda:\n") + (insert (capitalize (symbol-name (org-agenda-ndays-to-span nd))) + "-agenda:\n") (add-text-properties s (1- (point)) (list 'face 'org-agenda-structure 'org-date-line t)) (while (setq d (pop day-numbers)) @@ -15598,6 +16520,9 @@ NDAYS defaults to `org-agenda-ndays'." (setq buffer-read-only t) (message ""))) +(defun org-agenda-ndays-to-span (n) + (cond ((< n 7) 'day) ((= n 7) 'week) ((< n 32) 'month) (t 'year))) + ;;; Agenda TODO list (defvar org-select-this-todo-keyword nil) @@ -16021,6 +16946,8 @@ the documentation of `org-diary'." (setq results (append results rtn)))))))) results)))) +;; FIXME: this works only if the cursor is not at the +;; beginning of the entry (defun org-entry-is-done-p () "Is the current entry marked DONE?" (save-excursion @@ -16787,7 +17714,8 @@ If ERROR is non-nil, throw an error, otherwise just return nil." (let ((buf (current-buffer))) (if (not (one-window-p)) (delete-window)) (kill-buffer buf) - (org-agenda-maybe-reset-markers 'force)) + (org-agenda-maybe-reset-markers 'force) + (org-remove-column-overlays)) ;; Maybe restore the pre-agenda window configuration. (and org-agenda-restore-windows-after-quit (not (eq org-agenda-window-setup 'other-frame)) @@ -16833,8 +17761,11 @@ When this is the global TODO list, a prefix argument will be interpreted." (cond (tdpos (goto-char tdpos)) ((eq org-agenda-type 'agenda) - (let ((org-agenda-overriding-arguments org-agenda-last-arguments)) - (setf (nth 1 org-agenda-overriding-arguments) nil) + (let* ((sd (time-to-days (current-time))) + (comp (org-agenda-compute-time-span sd org-agenda-span)) + (org-agenda-overriding-arguments org-agenda-last-arguments)) + (setf (nth 1 org-agenda-overriding-arguments) (car comp)) + (setf (nth 2 org-agenda-overriding-arguments) (cdr comp)) (org-agenda-redo) (org-agenda-find-today-or-agenda))) (t (error "Cannot find today"))))) @@ -16846,62 +17777,106 @@ When this is the global TODO list, a prefix argument will be interpreted." (point-min)))) (defun org-agenda-later (arg) - "Go forward in time by `org-agenda-ndays' days. -With prefix ARG, go forward that many times `org-agenda-ndays'." + "Go forward in time by thee current span. +With prefix ARG, go forward that many times the current span." (interactive "p") (org-agenda-check-type t 'agenda) - (let ((org-agenda-overriding-arguments - (list (car org-agenda-last-arguments) - (+ org-starting-day (* arg org-agenda-ndays)) - nil t))) + (let* ((span org-agenda-span) + (sd org-starting-day) + (greg (calendar-gregorian-from-absolute sd)) + greg2 nd) + (cond + ((eq span 'day) + (setq sd (+ arg sd) nd 1)) + ((eq span 'week) + (setq sd (+ (* 7 arg) sd) nd 7)) + ((eq span 'month) + (setq greg2 (list (+ (car greg) arg) (nth 1 greg) (nth 2 greg)) + sd (calendar-absolute-from-gregorian greg2)) + (setcar greg2 (1+ (car greg2))) + (setq nd (- (calendar-absolute-from-gregorian greg2) sd))) + ((eq span 'year) + (setq greg2 (list (car greg) (nth 1 greg) (+ arg (nth 2 greg))) + sd (calendar-absolute-from-gregorian greg2)) + (setcar (nthcdr 2 greg2) (1+ (nth 2 greg2))) + (setq nd (- (calendar-absolute-from-gregorian greg2) sd)))) + (let ((org-agenda-overriding-arguments + (list (car org-agenda-last-arguments) sd nd t))) (org-agenda-redo) - (org-agenda-find-today-or-agenda))) - + (org-agenda-find-today-or-agenda)))) + (defun org-agenda-earlier (arg) - "Go back in time by `org-agenda-ndays' days. -With prefix ARG, go back that many times `org-agenda-ndays'." + "Go backward in time by the current span. +With prefix ARG, go backward that many times the current span." (interactive "p") - (org-agenda-check-type t 'agenda) - (let ((org-agenda-overriding-arguments - (list (car org-agenda-last-arguments) - (- org-starting-day (* arg org-agenda-ndays)) - nil t))) - (org-agenda-redo) - (org-agenda-find-today-or-agenda))) - -(defun org-agenda-week-view () - "Switch to weekly view for agenda." - (interactive) - (org-agenda-check-type t 'agenda) - (if (= org-agenda-ndays 7) - (error "This is already the week view")) - (setq org-agenda-ndays 7) - (let ((org-agenda-overriding-arguments - (list (car org-agenda-last-arguments) - (or (get-text-property (point) 'day) - org-starting-day) - nil t))) - (org-agenda-redo) - (org-agenda-find-today-or-agenda)) - (org-agenda-set-mode-name) - (message "Switched to week view")) + (org-agenda-later (- arg))) (defun org-agenda-day-view () "Switch to daily view for agenda." (interactive) + (org-agenda-change-time-span 'day)) +(defun org-agenda-week-view () + "Switch to daily view for agenda." + (interactive) + (org-agenda-change-time-span 'week)) +(defun org-agenda-month-view () + "Switch to daily view for agenda." + (interactive) + (org-agenda-change-time-span 'month)) +(defun org-agenda-year-view () + "Switch to daily view for agenda." + (interactive) + (if (y-or-n-p "Are you sure you want to compute the agenda for an entire year? ") + (org-agenda-change-time-span 'year) + (error "Abort"))) + +(defun org-agenda-change-time-span (span) + "Change the agenda view to SPAN. +SPAN may be `day', `week', `month', `year'." (org-agenda-check-type t 'agenda) - (if (= org-agenda-ndays 1) - (error "This is already the day view")) - (setq org-agenda-ndays 1) - (let ((org-agenda-overriding-arguments - (list (car org-agenda-last-arguments) - (or (get-text-property (point) 'day) - org-starting-day) - nil t))) + (if (equal org-agenda-span span) + (error "Viewing span is already \"%s\"" span)) + (let* ((sd (or (get-text-property (point) 'day) + org-starting-day)) + (computed (org-agenda-compute-time-span sd span)) + (org-agenda-overriding-arguments + (list (car org-agenda-last-arguments) + (car computed) (cdr computed) t))) (org-agenda-redo) (org-agenda-find-today-or-agenda)) (org-agenda-set-mode-name) - (message "Switched to day view")) + (message "Switched to %s view" span)) + +(defun org-agenda-compute-time-span (sd span) + "Compute starting date and number of days for agenda. +SPAN may be `day', `week', `month', `year'. The return value +is a cons cell with the starting date and the number of days, +so that the date SD will be in that range." + (let* ((greg (calendar-gregorian-from-absolute sd)) + nd) + (cond + ((eq span 'day) + (setq nd 1)) + ((eq span 'week) + (let* ((nt (calendar-day-of-week + (calendar-gregorian-from-absolute sd))) + (n1 org-agenda-start-on-weekday) + (d (- nt n1))) + (setq sd (- sd (+ (if (< d 0) 7 0) d))) + (setq nd 7))) + ((eq span 'month) + (setq sd (calendar-absolute-from-gregorian + (list (car greg) 1 (nth 2 greg))) + nd (- (calendar-absolute-from-gregorian + (list (1+ (car greg)) 1 (nth 2 greg))) + sd))) + ((eq span 'year) + (setq sd (calendar-absolute-from-gregorian + (list 1 1 (nth 2 greg))) + nd (- (calendar-absolute-from-gregorian + (list 1 1 (1+ (nth 2 greg)))) + sd)))) + (cons sd nd))) ;; FIXME: this no longer works if user make date format that starts with a blank (defun org-agenda-next-date-line (&optional arg) @@ -18022,6 +18997,7 @@ The images can be removed again with \\[org-ctrl-c-ctrl-c]." (:emphasize . org-export-with-emphasize) (:sub-superscript . org-export-with-sub-superscripts) (:footnotes . org-export-with-footnotes) + (:property-drawer . org-export-with-property-drawer) (:TeX-macros . org-export-with-TeX-macros) (:LaTeX-fragments . org-export-with-LaTeX-fragments) (:skip-before-1st-heading . org-export-skip-text-before-1st-heading) @@ -18079,6 +19055,7 @@ The images can be removed again with \\[org-ctrl-c-ctrl-c]." ("|" . :tables) ("^" . :sub-superscript) ("f" . :footnotes) + ("p" . :property-drawer) ("*" . :emphasize) ("TeX" . :TeX-macros) ("LaTeX" . :LaTeX-fragments) @@ -18524,6 +19501,12 @@ translations. There is currently no way for users to extend this.") b (org-end-of-subtree t)) (if (> b a) (delete-region a b))))) + ;; Get rid of property drawers + (unless org-export-with-property-drawer + (goto-char (point-min)) + (while (re-search-forward "^[ \t]*:PROPERTIES:[ \t]*\n\\([^@]*?\n\\)?[ \t]*:END:[ \t]*\n" nil t) + (replace-match ""))) + ;; Protect stuff from HTML processing (goto-char (point-min)) (while (re-search-forward "^[ \t]*:.*\\(\n[ \t]*:.*\\)*" nil t) @@ -18888,7 +19871,12 @@ underlined headlines. The default is 3." (org-format-table-ascii table-buffer) "\n") "\n"))) (t - (insert (org-fix-indentation line org-ascii-current-indentation) "\n")))) + (setq line (org-fix-indentation line org-ascii-current-indentation)) + (if (and org-export-with-fixed-width + (string-match "^\\([ \t]*\\)\\(:\\)" line)) + (setq line (replace-match "\\1" nil nil line))) + (insert line "\n")))) + (normal-mode) ;; insert the table of contents @@ -19061,7 +20049,7 @@ Does include HTML export options as well as TODO and CATEGORY stuff." #+EMAIL: %s #+LANGUAGE: %s #+TEXT: Some descriptive text to be emitted. Several lines OK. -#+OPTIONS: H:%d num:%s toc:%s \\n:%s @:%s ::%s |:%s ^:%s f:%s *:%s TeX:%s LaTeX:%s skip:%s +#+OPTIONS: H:%d num:%s toc:%s \\n:%s @:%s ::%s |:%s ^:%s f:%s *:%s TeX:%s LaTeX:%s skip:%s p:%s #+CATEGORY: %s #+SEQ_TODO: %s #+TYP_TODO: %s @@ -19085,6 +20073,7 @@ Does include HTML export options as well as TODO and CATEGORY stuff." org-export-with-TeX-macros org-export-with-LaTeX-fragments org-export-skip-text-before-1st-heading + org-export-with-property-drawer (file-name-nondirectory buffer-file-name) "TODO FEEDBACK VERIFY DONE" "Me Jason Marie DONE" @@ -19900,7 +20889,7 @@ lang=\"%s\" xml:lang=\"%s\"> (nreverse rtn)))) (defun org-colgroup-info-to-vline-list (info) - (let (vl new last rtn line) + (let (vl new last) (while info (setq last new new (pop info)) (if (or (memq last '(:end :startend)) @@ -20433,6 +21422,7 @@ When COMBINE is non nil, add the category to each line." (sexp-buffer (get-buffer-create "*ical-tmp*"))) (save-excursion (goto-char (point-min)) + (debug) (while (re-search-forward re1 nil t) (catch :skip (org-agenda-skip) @@ -20445,10 +21435,14 @@ When COMBINE is non nil, add the category to each line." (progn (goto-char (match-end 0)) (setq ts2 (match-string 1) inc nil)) - (setq ts2 ts - tmp (buffer-substring (max (point-min) + (setq tmp (buffer-substring (max (point-min) (- pos org-ds-keyword-length)) pos) + ts2 (if (string-match "[0-9]\\{1,2\\}:[0-9][0-9]-\\([0-9]\\{1,2\\}:[0-9][0-9]\\)" ts) + (progn + (setq inc nil) + (replace-match "\\1" t nil ts)) + ts) deadlinep (string-match org-deadline-regexp tmp) scheduledp (string-match org-scheduled-regexp tmp) ;; donep (org-entry-is-done-p) @@ -20765,7 +21759,7 @@ The XOXO buffer is named *xoxo-*" (org-defkey org-mode-map [(control ?\')] 'org-cycle-agenda-files) (org-defkey org-mode-map "\C-c[" 'org-agenda-file-to-front) (org-defkey org-mode-map "\C-c]" 'org-remove-file) -(org-defkey org-mode-map "\C-c-" 'org-table-insert-hline) +(org-defkey org-mode-map "\C-c-" 'org-ctrl-c-minus) (org-defkey org-mode-map "\C-c^" 'org-sort) (org-defkey org-mode-map "\C-c\C-c" 'org-ctrl-c-ctrl-c) (org-defkey org-mode-map "\C-c#" 'org-update-checkbox-count) @@ -20802,6 +21796,8 @@ The XOXO buffer is named *xoxo-*" (org-defkey org-mode-map "\C-c\C-x\C-l" 'org-preview-latex-fragment) (org-defkey org-mode-map "\C-c\C-x\C-b" 'org-toggle-checkbox) +(define-key org-mode-map "\C-c\C-x\C-c" 'org-columns) + (when (featurep 'xemacs) (org-defkey org-mode-map 'button3 'popup-mode-menu)) @@ -21200,11 +22196,24 @@ Calls `org-table-next-row' or `newline', depending on context. See the individual commands for more information." (interactive) (cond + ((bobp) (newline)) ((org-at-table-p) (org-table-justify-field-maybe) (call-interactively 'org-table-next-row)) (t (newline)))) +(defun org-ctrl-c-minus () + "Insert separator line in table or modify bullet type in list. +Calls `org-table-insert-hline' or `org-cycle-list-bullet', +depending on context." + (interactive) + (cond + ((org-at-table-p) + (call-interactively 'org-table-insert-hline)) + ((org-in-item-p) + (call-interactively 'org-cycle-list-bullet)) + (t (error "`C-c -' does have no function here.")))) + (defun org-meta-return (&optional arg) "Insert a new heading or wrap a region in a table. Calls `org-insert-heading' or `org-table-wrap-region', depending on context. @@ -21241,7 +22250,7 @@ See the individual commands for more information." ["Insert Row" org-shiftmetadown (org-at-table-p)] ["Sort lines in region" org-table-sort-lines (org-at-table-p)] "--" - ["Insert Hline" org-table-insert-hline (org-at-table-p)]) + ["Insert Hline" org-ctrl-c-minus (org-at-table-p)]) ("Rectangle" ["Copy Rectangle" org-copy-special (org-at-table-p)] ["Cut Rectangle" org-cut-special (org-at-table-p)] @@ -21364,6 +22373,9 @@ See the individual commands for more information." ; (or (org-on-heading-p) (org-at-item-p))] ; ["Update Statistics" org-update-checkbox-count t] ) + ("TAGS and Properties" + ["Set Tags" 'org-ctrl-c-ctrl-c (org-at-heading-p)] + ["Column view of properties" org-columns t]) ("Dates and Scheduling" ["Timestamp" org-time-stamp t] ["Timestamp (inactive)" org-time-stamp-inactive t] @@ -21784,7 +22796,15 @@ not an indirect buffer" (goto-char pos) (if (<= (current-column) (current-indentation)) (indent-line-to column) - (save-excursion (indent-line-to column))))) + (save-excursion (indent-line-to column))) + (setq column (current-column)) + (beginning-of-line 1) + (if (looking-at + "\\([ \t]+\\)\\(:[0-9a-zA-Z]+:\\)[ \t]*\\(\\S-.*\\(\\S-\\|$\\)\\)") + (replace-match (concat "\\1" (format org-property-format + (match-string 2) (match-string 3))) + t nil)) + (move-to-column column))) (defun org-set-autofill-regexps () (interactive) @@ -22080,6 +23100,8 @@ Still experimental, may disappear in the furture." ;; make tree, check each match with the callback (org-occur "CLOSED: +\\[\\(.*?\\)\\]" nil callback))) + + ;;;; Finish up (provide 'org) @@ -22088,4 +23110,3 @@ Still experimental, may disappear in the furture." ;; arch-tag: e77da1a7-acc7-4336-b19e-efa25af3f9fd ;;; org.el ends here - diff --git a/org.pdf b/org.pdf index 6f7138152..51e5cb044 100644 Binary files a/org.pdf and b/org.pdf differ diff --git a/org.texi b/org.texi index 6281f1874..c82df7414 100644 --- a/org.texi +++ b/org.texi @@ -3,8 +3,8 @@ @setfilename ../info/org @settitle Org Mode Manual -@set VERSION 4.79 -@set DATE June 2007 +@set VERSION 5.01 +@set DATE July 2007 @dircategory Emacs @direntry @@ -81,6 +81,7 @@ Software Foundation raise funds for GNU development.'' * Hyperlinks:: Notes in context * TODO items:: Every tree branch can be a TODO item * Tags:: Tagging headlines and matching sets of tags +* Properties:: * Timestamps:: Assign date and time to items * Agenda views:: Collecting information into views * Embedded LaTeX:: LaTeX fragments and formulas @@ -112,6 +113,7 @@ Document Structure * Archiving:: Move done task trees to a different place * Sparse trees:: Matches embedded in context * Plain lists:: Additional structure within an entry +* Drawers:: Archiving @@ -179,6 +181,19 @@ Tags * Setting tags:: How to assign tags to a headline * Tag searches:: Searching for combinations of tags +Properties + +* Property syntax:: How properties are spelled out +* Special properties:: Access to other Org-mode features +* Property searches:: Matching property values +* Column view:: Tabular viewing and editing +* Property API:: Properties for Lisp programmers + +Column View + +* Defining columns:: The COLUMNS format property +* Using column view:: How to create and use column view + Timestamps * Time stamps:: Assigning a time to a tree entry @@ -215,7 +230,7 @@ The built-in agenda views * Weekly/Daily agenda:: The calendar page with current tasks * Global TODO list:: All unfinished action items -* Matching headline tags:: Structured information with fine-tuned search +* Matching tags and properties:: Structured information with fine-tuned search * Timeline:: Time-sorted view for single file * Stuck projects:: Find projects you need to review @@ -308,6 +323,7 @@ Extensions, Hooks and Hacking * Tables in arbitrary syntax:: Orgtbl for LaTeX and other programs * Dynamic blocks:: Automatically filled blocks * Special agenda views:: Customized views +* Using the property API:: Writing programs that use entry properties Tables in arbitrary syntax @@ -333,7 +349,7 @@ Tables in arbitrary syntax @section Summary @cindex summary -Org-mode is a mode for keeping notes, maintaining ToDo lists, and doing +Org-mode is a mode for keeping notes, maintaining TODO lists, and doing project planning with a fast and effective plain-text system. Org-mode develops organizational tasks around NOTES files that contain @@ -341,7 +357,7 @@ lists or information about projects as plain text. Org-mode 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. Org-mode supports ToDo items, deadlines, +with a built-in table editor. Org-mode supports TODO items, deadlines, time stamps, and scheduling. It dynamically compiles entries into an agenda that utilizes and smoothly integrates much of the Emacs calendar and diary. Plain text URL-like links connect to websites, emails, @@ -564,6 +580,7 @@ edit the structure of the document. * Archiving:: Move done task trees to a different place * Sparse trees:: Matches embedded in context * Plain lists:: Additional structure within an entry +* Drawers:: @end menu @node Outlines, Headlines, Document structure, Document structure @@ -991,7 +1008,7 @@ XEmacs uses selective display for outlining, not text properties.}. 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, , Sparse trees, Document structure +@node Plain lists, Drawers, Sparse trees, Document structure @section Plain lists @cindex plain lists @cindex lists, plain @@ -1017,9 +1034,9 @@ the 2--digit numbers must be written left-aligned with the other numbers in the list. Indentation also determines the end of a list item. It ends before the next line that is indented like the bullet/number, or less. Empty lines are part of the previous item, so you can have -several paragraphs in one item. If you would like an emtpy line to +several paragraphs in one item. If you would like an empty line to terminate all currently open plain lists, configure the variable -@code{org-empty-line-terminates-plain-lists}. Here is an for example: +@code{org-empty-line-terminates-plain-lists}. Here is an example: @example @group @@ -1097,8 +1114,37 @@ If there is a checkbox (@pxref{Checkboxes}) in the item line, toggle the state of the checkbox. If not, make this command makes sure that all the items on this list level use the same bullet. Furthermore, if this is an ordered list, make sure the numbering is ok. +@kindex C-c - +@item C-c - +Cycle the entire list level through the different itemize/enumerate +bullets (@samp{-}, @samp{+}, @samp{*}, @samp{1.}, @samp{1)}). +With prefix arg, select the nth bullet from this list. @end table +@node Drawers, , Plain lists, Document structure +@section Drawers +@cindex drawers + +Sometimes you want to keep information associated with an entry, but you +normally don't want to see it, except when explicitly asking for it. +For this, Org-mode has @emph{drawers}. Drawers need to be configured +with the variable @code{org-drawers}, and look like this: + +@example +** This is a headline + Still outside the drawer + :DRAWERNAME: + This is inside the drawer. + :END: + After the drawer. +@end example + +Visibility cycling (@pxref{Visibility cycling}) on the headline will +hide and show 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 @key{TAB} there. Org-mode uses a drawer for +storing properties (@pxref{Properties}). + @node Tables, Hyperlinks, Document structure, Top @chapter Tables @cindex tables @@ -1557,12 +1603,23 @@ see the @samp{E} mode switch below). If there are no non-empty fields, @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}. If you have the @file{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{@file{Constant.el} can supply the -values of constants in two different unit systems, @code{SI} and -@code{cgs}. Which one is used depends on the value of the variable +@code{org-table-formula-constants}, and locally (for the file) through a +line like + +@example +#+CONSTANTS: c=299792458. pi=3.14 eps=2.4e-6 +@end example + +@noindent +Also properties (@pxref{Properties}) 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 @file{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{@file{Constant.el} can supply the values of +constants in two different unit systems, @code{SI} and @code{cgs}. +Which one is used depends on the value of the variable @code{constants-unit-system}. You can use the @code{#+STARTUP} options @code{constSI} and @code{constcgs} to set this value for the current buffer.}. Column names and parameters can be specified in special table @@ -2511,6 +2568,8 @@ insertion of content: %a @r{annotation, normally the link created with @code{org-store-link}} %i @r{initial content, the region when remember is called with C-u.} @r{The entire text will be indented like @code{%i} itself.} +%^g @r{prompt for tags, with completion on tags in target file.} +%^G @r{prompt for tags, with completion all tags in all agenda files.} %:keyword @r{specific information for certain link types, see below} @end example @@ -2663,6 +2722,9 @@ the TODO entries directly from that buffer (@pxref{Agenda commands}). @c @item @code{org-agenda-include-all-todo} @c If you would like to have all your TODO items listed as part of your @c agenda, customize the variable @code{org-agenda-include-all-todo}. +@kindex S-M-@key{RET} +@item S-M-@key{RET} +Insert a new TODO entry below the current one. @end table @node TODO extensions, Priorities, TODO basics, TODO items @@ -2968,7 +3030,7 @@ back into synch. Or simply toggle any checkbox twice with @kbd{C-c C-c}. @end table -@node Tags, Timestamps, TODO items, Top +@node Tags, Properties, TODO items, Top @chapter Tags @cindex tags @cindex headline tagging @@ -3161,7 +3223,7 @@ Create a sparse tree with all headlines matching a tags search. With a @kindex C-c a m @item C-c a m Create a global list of tag matches from all agenda files. -@xref{Matching headline tags}. +@xref{Matching tags and properties}. @kindex C-c a M @item C-c a M Create a global list of tag matches from all agenda files, but check @@ -3224,7 +3286,215 @@ instead of any TAG an expression like @samp{LEVEL=3}. For example, a search @samp{+LEVEL=3+BOSS/-DONE} lists all level three headlines that have the tag BOSS and are @emph{not} marked with the todo keyword DONE. -@node Timestamps, Agenda views, Tags, Top +@node Properties, Timestamps, Tags, Top +@chapter Properties +@cindex properties + +Properties are a set of key-value pairs associated with an entry. There +are two main applications for properties in Org-mode. First, properties +are like tags, but with a value. For example, in a file where you +document bugs and plan releases of a piece of software, instead of using +tags like @code{:release_1:}, @code{:release_2:}, it can be more +efficient to use a property @code{RELEASE} with a value @code{1.0} or +@code{2.0}. Second, you can use properties to implement (very basic) +database capabilities in an Org-mode buffer, for example to create a +list of Music CD's you own. + +@menu +* Property syntax:: How properties are spelled out +* Special properties:: Access to other Org-mode features +* Property searches:: Matching property values +* Column view:: Tabular viewing and editing +* Property API:: Properties for Lisp programmers +@end menu + +@node Property syntax, Special properties, Properties, Properties +@section Property Syntax + +Properties are key-value pairs. They need to be inserted into a special +drawer (@pxref{Drawers}) with the name @code{PROPERTIES}. Each property +is specified on a single line, with the key (surrounded by colons) +first, and the value after it. Here is an example: + +@example +* CD collection +** Classic +*** Goldberg Variations + :PROPERTIES: + :Title: Goldberg Variations + :Composer: J.S. Bach + :Artist: Glen Gould + :END: +@end example + +@noindent +The following commands help to insert properties: + +@table @kbd +@kindex M-@key{TAB} +@item M-@key{TAB} +After an initial colon in a line, complete property keys. All keys used +in the current file will be offered as possible completions. +@end table + + + +@node Special properties, Property searches, Property syntax, Properties +@section Special Properties + +Several properties are special, because they can be used to access other +features of Org-mode like the TODO status: + +@example +TODO @r{The TODO keyword of the entry.} +TAGS @r{The tags defined directly in the headline.} +ALLTAGS @r{All tags, including inherited ones.} +PRIORITY @r{The priority of the entry, a string with a single letter.} +DEADLINE @r{The deadline time string, without the angular brackets.} +SCHEDULED @r{The scheduling time stamp, without the angular brackets.} +@end example + +@node Property searches, Column view, Special properties, Properties +@section Property searches + +To create sparse trees and special lists with selection based on +properties, the same commands are used as for tag searches (@pxref{Tag +searches}), and the same logic applies. For example, a search string + +@example ++WORK-BOSS+PRIORITY="A"+coffee="unlimited"+with=@{Sarah\|Denny@} +@end example + +@noindent +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}, and a @samp{:with:} property that is matched by +the regular expression @samp{Sarah\|Denny}. + +@node Column view, Property API, Property searches, Properties +@section Column View + +If different items in a document have similar properties, it can be nice +to view and edit those properties in a table-like format, in +@emph{column view}. Org-mode implements columns by overlaying a tabular +structure over the headline of an item. So the column view does not use +a special buffer, it happens in exactly the same buffer where the +outline is, and only temporarily changes the look of this buffer - not +the content. This has the advantage that you can still change the +visibility of the outline tree. For example, you get a compact table by +switching to CONTENTS view, 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 (@pxref{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 +@end menu + +@node Defining columns, Using column view, Column view, Column view +@subsection Defining Columns + +Setting up a column view first requires defining the columns. A column +definition is a property itself and looks like this: + +@example +:COLUMNS: %25ITEM %TAGS %PRIORITY %TODO +@end example + +This definition means that column 1 should be the first 25 characters of +the item itself, i.e. of the headline. You probably always should start +the column definition with the ITEM specifier - just select a useful +width for it. The other specifiers create columns for the local tags, +for the priority and for the TODO state. When no width is given after +the @samp{%} character, the column will be exactly as wide as it need to +be in order to fully display all values. + +If a @code{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. Here is an example: + +@example +* People + :PROPERTIES: + :COLUMNS: %25ITEM %Name + :END: +** Family + :PROPERTIES: + :COLUMNS: %25ITEM %Name %3Age + :END: +*** Sam + Info about Sam, including a property list with Name and Age. +*** Sarah + Info about Sarah, including a property list with Name and Age. +** Office + :PROPERTIES: + :COLUMNS: %25ITEM %Name %Function %Salary + :END: +*** Boss + Info about the Boss, including a property list with Name, + Function and Salary (if only we knew....). +@end example + +Now we have defined three different sets of columns. If you switch to +column view in the @emph{Family} section, you will get a different table +than if you do it in the @emph{Office} section. However, if you switch +to column view with the cursor on the @emph{People} section, the table +will cover all entries, but contain only the @emph{Name} column. + +If no COLUMNS property applies to a given location, Org-mode uses a +default format specified in the variable +@code{org-default-columns-format}. This format in particular also +applies when column view is invoked with the cursor before the first +headline. You can set the default format on a per-file basis with a +line (don't forget to press @kbd{C-c C-c} to activate any changes to +this line). + +@example +#+COLUMNS: %25ITEM ....." +@end example + +@node Using column view, , Defining columns, Column view +@subsection Using Column View + +@table @kbd +@kindex C-c C-x C-c +@item C-c C-x C-c +Create the column view for the local environment. This command searches +the hierarchy, up from point, for a @code{COLUMNS} property that defines +a format. When one is found, the column view table is established for +the entire subtree. +@item @key{left} @key{right} @key{up} @key{down} +Move through the column view from field to field. +@kindex e +@item e +Edit the property at point. For the special properties, this will +invoke the same interface that you normally use to change that +property. For example, when editing a TAGS property, the tag completion +or fast selection interface will pop up. +@kindex v +@item v +View the full value of this property. This is useful if the width of +the column is smaller than that of the value. +@kindex q +@item q +Exit column view. +@end table + +@node Property API, , Column view, Properties +@section The Property API + +There is a full API for accessing and changing properties. This API can +be used by Emacs Lisp programs to work with properties and to implement +features based on them. For more information see @ref{Using the +property API}. + +@node Timestamps, Agenda views, Properties, Top @chapter Timestamps @cindex time stamps @cindex date stamps @@ -3885,7 +4155,7 @@ Create the calendar-like agenda (@pxref{Weekly/Daily agenda}). Create a list of all TODO items (@pxref{Global TODO list}). @item m @r{/} M Create a list of headlines matching a TAGS expression (@pxref{Matching -headline tags}). +tags and properties}). @item L Create the timeline view for the current buffer (@pxref{Timeline}). @item # @r{/} ! @@ -3914,7 +4184,7 @@ 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 headline tags:: Structured information with fine-tuned search +* Matching tags and properties:: Structured information with fine-tuned search * Timeline:: Time-sorted view for single file * Stuck projects:: Find projects you need to review @end menu @@ -3988,11 +4258,11 @@ will be made in the agenda: #+CATEGORY: Holiday %%(org-calendar-holiday) ; special function for holiday names #+CATEGORY: Ann -%%(diary-anniversary 14 5 1956) Artur Dent %d is years old +%%(diary-anniversary 14 5 1956) Arthur Dent is %d years old %%(diary-anniversary 2 10 1869) Mahatma Gandhi would be %d years old @end example -@node Global TODO list, Matching headline tags, Weekly/Daily agenda, Built-in agenda views +@node Global TODO list, Matching tags and properties, Weekly/Daily agenda, Built-in agenda views @subsection The global TODO list @cindex global TODO list @cindex TODO list, global @@ -4046,9 +4316,10 @@ 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 headline tags, Timeline, Global TODO list, Built-in agenda views -@subsection Matching headline tags +@node Matching tags and properties, Timeline, Global TODO list, Built-in agenda views +@subsection Matching Tags and Properties @cindex matching, of tags +@cindex matching, of properties @cindex tags view If headlines in the agenda files are marked with @emph{tags} @@ -4074,7 +4345,7 @@ together with a tags match is also possible, see @ref{Tag searches}. The commands available in the tags list are described in @ref{Agenda commands}. -@node Timeline, Stuck projects, Matching headline tags, Built-in agenda views +@node Timeline, Stuck projects, Matching tags and properties, Built-in agenda views @subsection Timeline for a single file @cindex timeline, single file @cindex time-sorted view @@ -4328,13 +4599,12 @@ as are entries that have been clocked on that day. @item o Delete other windows. @c -@kindex w -@item w -Switch to weekly view (7 days displayed together). -@c @kindex d -@item d -Switch to daily view (just one day displayed). +@kindex w +@kindex m +@kindex y +@item d w m y +Switch to day/week/month/year view. @c @kindex D @item D @@ -6033,6 +6303,7 @@ force publishing of all files by giving a prefix argument. @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 @@ -6058,10 +6329,14 @@ After @samp{\}, complete @TeX{} symbols supported by the exporter. After @samp{*}, complete headlines in the current buffer so that they can be used in search links like @samp{[[*find this headline]]}. @item -After @samp{:}, complete tags. The list of tags is taken from the -variable @code{org-tag-alist} (possibly set through the @samp{#+TAGS} -in-buffer option, @pxref{Setting tags}), or it is created dynamically -from all tags used in the current buffer. +After @samp{:} in a headline, complete tags. The list of tags is taken +from the variable @code{org-tag-alist} (possibly set through the +@samp{#+TAGS} in-buffer option, @pxref{Setting tags}), or it is created +dynamically 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 (@pxref{Link abbreviations}). @item @@ -6107,6 +6382,32 @@ activate the changes immediately. Otherwise they become effective only when the file is visited again in a new Emacs session. @table @kbd +@item #+ARCHIVE: %s_done:: +This line sets the archive location for the agenda file. It applies for +all subsequent lines until the next @samp{#+CATEGORY} line, or the end +of the file. The first such line also applies to any entries before it. +The corresponding variable is @code{org-archive-location}. +@item #+CATEGORY: +This line sets the category for the agenda file. The category applies +for all subsequent lines until the next @samp{#+CATEGORY} line, or the +end of the file. The first such line also applies to any entries before it. +@item #+COLUMNS: %25ITEM ..... +Set the default format for columns view. This format applies when +columns view is invoked in location where no COLUMNS property applies. +@item #+CONSTANTS: name1=value1 ... +Set file-local values for constants to be used in table formulas. This +line set the local variable @code{org-table-formula-constants-local}. +The global version of theis variable is +@code{org-table-formula-constants}. +corresponding +@item #+LINK: linkword replace +These lines (several are allowed) specify link abbreviations. +@xref{Link abbreviations}. The corresponding variable is +@code{org-link-abbrev-alist}. +@item #+PRIORITIES: highest lowest default +This line sets the limits and the default for the priorities. All three +must be either letters A-Z or numbers 0-9. The highest priority must +have a lower ASCII number that the lowest priority. @item #+STARTUP: This line sets options to be used at startup of org-mode, when an Org-mode file is being visited. The first set of options deals with the @@ -6178,36 +6479,19 @@ The following options influence the table spreadsheet (variable constcgs @r{@file{constants.el} should use the c-g-s unit system} constSI @r{@file{constants.el} should use the SI unit system} @end example -@item #+SEQ_TODO: #+TYP_TODO: -These lines set the TODO keywords and their interpretation in the -current file. The corresponding variables are @code{org-todo-keywords} -and @code{org-todo-interpretation}. @item #+TAGS: TAG1(c1) TAG2(c2) These lines (several such lines are allowed) specify the legal tags in this file, and (potentially) the corresponding @emph{fast tag selection} keys. The corresponding variable is @code{org-tag-alist}. -@item #+LINK: linkword replace -These lines (several are allowed) specify link abbreviations. -@xref{Link abbreviations}. The corresponding variable is -@code{org-link-abbrev-alist}. -@item #+CATEGORY: -This line sets the category for the agenda file. The category applies -for all subsequent lines until the next @samp{#+CATEGORY} line, or the -end of the file. The first such line also applies to any entries before it. -@item #+ARCHIVE: %s_done:: -This line sets the archive location for the agenda file. It applies for -all subsequent lines until the next @samp{#+CATEGORY} line, or the end -of the file. The first such line also applies to any entries before it. -The corresponding variable is @code{org-archive-location}. -@item #+PRIORITIES: highest lowest default -This line sets the limits and the default for the priorities. All three -must be either letters A-Z or numbers 0-9. The highest priority must -have a lower ASCII number that the lowest priority. @item #+TBLFM: This line contains the formulas for the table directly above the line. @item #+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+TEXT:, #+OPTIONS: These lines provide settings for exporting files. For more details see @ref{Export options}. +@item #+SEQ_TODO: #+TYP_TODO: +These lines set the TODO keywords and their interpretation in the +current file. The corresponding variables are @code{org-todo-keywords} +and @code{org-todo-interpretation}. @end table @node The very busy C-c C-c key, Clean view, In-buffer settings, Miscellaneous @@ -6575,6 +6859,7 @@ Org-mode. * Tables in arbitrary syntax:: Orgtbl for LaTeX and other programs * Dynamic blocks:: Automatically filled blocks * Special agenda views:: Customized views +* Using the property API:: Writing programs that use entry properties @end menu @node Extensions, Tables in arbitrary syntax, Extensions and Hacking, Extensions and Hacking @@ -6948,7 +7233,7 @@ you could add the function @code{org-update-all-dblocks} to a hook, for example @code{before-save-hook}. @code{org-update-all-dblocks} is written in a way that is does nothing in buffers that are not in Org-mode. -@node Special agenda views, , Dynamic blocks, Extensions and Hacking +@node Special agenda views, Using the property API, Dynamic blocks, Extensions and Hacking @section Special Agenda Views @cindex agenda views, user-defined @@ -7001,6 +7286,44 @@ MATCH is being ignored." (org-todo-list "PROJECT"))) @end lisp +@node Using the property API, , Special agenda views, Extensions and Hacking +@section Using the property API +@cindex API, for properties + +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 POM. +This includes the TODO keyword, the tags, time strings for deadline, +scheduled, and clocking, and any additional properties defined in the +entry. The return value is an alist, keys may occur multiple times +if the property key was used several times. +POM may also be nil, in which case the current entry is used. +If WHICH is nil or `all', get all properties. If WHICH is +`special' or `standard', only get that subclass. +@end defun +@defun org-entry-get pom property &optional inherit +Get value of PROPERTY for entry at point-or-marker POM. +If INHERIT is non-nil and the entry does not have the property, +then also check higher levels of the hierarchy. +@end defun + +@defun org-entry-delete pom property +Delete the property PROPERTY from entry at point-or-marker POM. +@end defun + +@defun org-entry-put pom property value +Set PROPERTY to VALUE 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 at point. +@end defun @node History and Acknowledgments, Index, Extensions and Hacking, Top @appendix History and Acknowledgments @@ -7025,7 +7348,7 @@ goals that Org-mode still has today: To create 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, hundreds of emails to me or on +Since the first release, literally thousands of emails to me or on @code{emacs-orgmode@@gnu.org} have provided a constant stream of bug reports, feedback, new ideas, and sometimes patches and add-on code. Many thanks to everyone who has helped to improve this package. I am @@ -7036,6 +7359,8 @@ let me know. @itemize @bullet +@item +@i{Russel Adams} came up with the idea for drawers. @item @i{Thomas Baumann} contributed the code for links to the MH-E email system. @@ -7054,7 +7379,9 @@ calculations and improved XEmacs compatibility, in particular by porting @item @i{Sacha Chua} suggested to copy some linking code from Planner. @item -@i{Eddward DeVilla} proposed and tested checkbox statistics. +@i{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 @i{Kees Dullemond} used to edit projects lists directly in HTML and so inspired some of the early development, including HTML export. He also @@ -7078,6 +7405,9 @@ translated David O'Toole's tutorial into French. @item @i{Kai Grossjohann} pointed out key-binding conflicts with other packages. @item +@i{Scott Jaderholm} proposed footnotes, control over whitespace between +folded entries, and column view for properties. +@item @i{Shidai Liu} ("Leo") asked for embedded LaTeX and tested it. He also provided frequent feedback and some patches. @item diff --git a/orgcard.pdf b/orgcard.pdf index cb4e3f02f..02c06448d 100644 Binary files a/orgcard.pdf and b/orgcard.pdf differ diff --git a/orgcard.tex b/orgcard.tex index fb1ef1135..d9f60f62f 100644 --- a/orgcard.tex +++ b/orgcard.tex @@ -1,5 +1,5 @@ % Reference Card for Org Mode -\def\orgversionnumber{4.79} +\def\orgversionnumber{5.01} \def\versionyear{2007} % latest update \def\year{2007} % latest copyright year @@ -621,7 +621,7 @@ To set categories, add lines like$^2$: {\bf Change display} \key{delete other windows}{o} -\key{switch to daily / weekly view}{d / w} +\key{switch to day/week/month/year view}{d w m y} \key{toggle inclusion of diary entries}{D} \key{toggle time grid for daily schedule}{g} \key{toggle display of logbook entries}{l} diff --git a/orgcard_letter.pdf b/orgcard_letter.pdf index 48ece6d3f..3af5d77e1 100644 Binary files a/orgcard_letter.pdf and b/orgcard_letter.pdf differ diff --git a/orgcard_letter.ps b/orgcard_letter.ps index 03614d872..d272b9852 100644 --- a/orgcard_letter.ps +++ b/orgcard_letter.ps @@ -11,7 +11,7 @@ %DVIPSCommandLine: dvips -t landscape -o orgcard_letter.ps %+ orgcard_letter.dvi %DVIPSParameters: dpi=600, compressed -%DVIPSSource: TeX output 2007.06.14:1329 +%DVIPSSource: TeX output 2007.06.20:0644 %%BeginProcSet: texc.pro %! /TeXDict 300 dict def TeXDict begin/N{def}def/B{bind def}N/S{exch}N/X{S