diff --git a/org b/org index d5fb9f20b..4da0cd6d8 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.24). + This manual is for Org-mode (version 4.26). Copyright (C) 2004, 2005, 2006 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.24). +This manual is for Org-mode (version 4.26). Copyright (C) 2004, 2005, 2006 Free Software Foundation @@ -46,13 +46,13 @@ This manual is for Org-mode (version 4.24). * Menu: * Introduction:: Getting started -* Document Structure:: A tree works like your brain +* Document structure:: A tree works like your brain * Tables:: Pure magic for quick formatting * Hyperlinks:: Notes in context * TODO items:: Every tree branch can be a TODO item * Timestamps:: Assign date and time to items * Tags:: Tagging headlines and matching sets of tags -* Agenda Views:: Collecting information into views +* Agenda views:: Collecting information into views * Exporting:: Sharing and publishing of notes * Miscellaneous:: All the rest which did not fit elsewhere * Index:: The fast road to specific information @@ -66,7 +66,7 @@ Introduction * Installation and activation:: How to install Org-mode * Feedback:: Bug reports, ideas, patches etc. -Document Structure +Document structure * Outlines:: Org-mode is based on outline-mode * Headlines:: How to typeset org-tree headlines @@ -75,7 +75,7 @@ Document Structure * Structure editing:: Changing sequence and level of headlines * Archiving:: Move done task trees to a different place * Sparse trees:: Matches embedded in context -* Plain Lists:: Editing hand-formatted lists +* Plain lists:: Editing hand-formatted lists Tables @@ -99,7 +99,7 @@ Hyperlinks * Link format:: How links in Org-mode are formatted * Internal links:: Links to other places in the current file * External links:: URL-like links to the world -* Managing links:: Creating, inserting and following +* Handling links:: Creating, inserting and following * Search Options:: Linking to a specific location * Remember:: Org-trees store quick notes @@ -132,11 +132,11 @@ Tags * Setting tags:: How to assign tags to a headline * Tag searches:: Searching for combinations of tags -Agenda Views +Agenda views * Agenda files:: Files being searched for agenda information * Agenda dispatcher:: Keyboard access to agenda views -* Weekly/Daily Agenda:: The calendar page with current tasks +* 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 * Timeline:: Time-sorted view for single file @@ -177,7 +177,7 @@ Miscellaneous * Acknowledgments:: These people provided feedback and more  -File: org, Node: Introduction, Next: Document Structure, Prev: Top, Up: Top +File: org, Node: Introduction, Next: Document structure, Prev: Top, Up: Top 1 Introduction ************** @@ -212,10 +212,10 @@ can be exported as a structured ASCII file, as HTML, or (todo and agenda items only) as an iCalendar file. Org-mode keeps simple things simple. When first fired up, it should -feel like a simple but easy to use outliner. Complexity is not -imposed, but a large amount of functionality is available when you need -it. Org-mode can be used on different levels and in different ways, -for example: +feel like a simple, easy to use outliner. Complexity is not imposed, +but a large amount of functionality is available when you need it. +Org-mode can be used on different levels and in different ways, for +example: * as an outline extension with visibility cycling and structure editing * as an ASCII system and table editor for taking structured notes @@ -294,7 +294,7 @@ information about: Thank you for helping to improve this mode.  -File: org, Node: Document Structure, Next: Tables, Prev: Introduction, Up: Top +File: org, Node: Document structure, Next: Tables, Prev: Introduction, Up: Top 2 Document Structure ******************** @@ -311,10 +311,10 @@ edit the structure of the document. * Structure editing:: Changing sequence and level of headlines * Archiving:: Move done task trees to a different place * Sparse trees:: Matches embedded in context -* Plain Lists:: Editing hand-formatted lists +* Plain lists:: Editing hand-formatted lists  -File: org, Node: Outlines, Next: Headlines, Prev: Document Structure, Up: Document Structure +File: org, Node: Outlines, Next: Headlines, Prev: Document structure, Up: Document structure 2.1 Outlines ============ @@ -329,7 +329,7 @@ outlines by compressing the entire show/hide functionality into a single command `org-cycle', which is bound to the key.  -File: org, Node: Headlines, Next: Visibility cycling, Prev: Outlines, Up: Document Structure +File: org, Node: Headlines, Next: Visibility cycling, Prev: Outlines, Up: Document structure 2.2 Headlines ============= @@ -350,7 +350,7 @@ that has whitespace followed by a single star as headline starters. *Note Clean view:: describes a setup to realize this.  -File: org, Node: Visibility cycling, Next: Motion, Prev: Headlines, Up: Document Structure +File: org, Node: Visibility cycling, Next: Motion, Prev: Headlines, Up: Document structure 2.3 Visibility cycling ====================== @@ -389,7 +389,7 @@ basis by adding one of the following lines anywhere in the buffer: #+STARTUP: showall  -File: org, Node: Motion, Next: Structure editing, Prev: Visibility cycling, Up: Document Structure +File: org, Node: Motion, Next: Structure editing, Prev: Visibility cycling, Up: Document structure 2.4 Motion ========== @@ -420,16 +420,21 @@ The following commands jump to other headlines in the buffer. hierarchy above it is made visible.  -File: org, Node: Structure editing, Next: Archiving, Prev: Motion, Up: Document Structure +File: org, Node: Structure editing, Next: Archiving, Prev: Motion, Up: Document structure 2.5 Structure editing ===================== `M-' Insert new heading with same level as current. If the cursor is - in a plain list item, a new item is created. To force creation of - a new headline, use a prefix arg, or first press to get to - the beginning of the next line. + in a plain list item, a new item is created (*note Plain lists::). + To force creation of a new headline, use a prefix arg, or first + press to get to the beginning of the next line. When this + command is used in the middle of a line, the line is split and the + rest of the line becomes the new headline. If the command is used + at the beginning of a headline, the new headline is created before + the current line. It at the beginning of any other line, the + content of that line is made the new heading. `M-S-' Insert new TODO entry with same level as current heading. @@ -474,7 +479,7 @@ inside a table (*note Tables::), the Meta-Cursor keys have different functionality.  -File: org, Node: Archiving, Next: Sparse trees, Prev: Structure editing, Up: Document Structure +File: org, Node: Archiving, Next: Sparse trees, Prev: Structure editing, Up: Document structure 2.6 Archiving ============= @@ -494,7 +499,7 @@ are also using the Org-mode agenda, archiving to a different file is a good way to keep archived trees from contributing agenda items.  -File: org, Node: Sparse trees, Next: Plain Lists, Prev: Archiving, Up: Document Structure +File: org, Node: Sparse trees, Next: Plain lists, Prev: Archiving, Up: Document structure 2.7 Sparse trees ================ @@ -544,12 +549,12 @@ can then be printed in any desired way. `org-show-following-heading'. (2) This does not work under XEmacs, because XEmacs uses selective -display for outlining, not text properties +display for outlining, not text properties.  -File: org, Node: Plain Lists, Prev: Sparse trees, Up: Document Structure +File: org, Node: Plain lists, Prev: Sparse trees, Up: Document structure -2.8 Plain Lists +2.8 Plain lists =============== Headlines define both the structure of the Org-mode file, and also lists @@ -577,6 +582,7 @@ is indented like the bullet/number, or less. For example: 3. Peter Jackson being shot by Legolas - on DVD only He makes a really funny face when it happens. + But in the end, not individual scenes matter but the film as a whole. Org-mode supports these lists by tuning filling and wrapping commands to correctly deal with them. Furthermore, the following commands act @@ -591,8 +597,14 @@ the bullet or number). remain completely separated. `M-' - Insert new item at current level. With prefix arg, for a new - heading. + Insert new item at current level. With prefix arg, force a new + heading (*note Structure editing::). If this command is used in + the middle of a line, the line is _split_ and the rest of the line + becomes the new item. If this command is executed in the + _whitespace before a bullet or number_, the new item is created + _before_ the current item. If the command is executed in the + white space before the text that is part of an item but does not + contain the bullet, a bullet is added to the current line. `M-S-' `M-S-' @@ -622,7 +634,7 @@ even though `*' is supported, it may be better to not use it for plain list items  -File: org, Node: Tables, Next: Hyperlinks, Prev: Document Structure, Up: Top +File: org, Node: Tables, Next: Hyperlinks, Prev: Document structure, Up: Top 3 Tables ******** @@ -862,8 +874,8 @@ File: org, Node: Narrow columns, Next: Table calculations, Prev: Built-in tab The width of columns is automatically determined by the table editor. Sometimes a single field or a few fields need to carry more text, leading to inconveniently wide columns. To limit(1) the width of a -column, one field anywhere in the column must carry the string `' -where `N' is an integer specifying the width of the column in +column, one field anywhere in the column may contain just the string +`' where `N' is an integer specifying the width of the column in characters. The next re-align will then set the width of this column to no more than this value. @@ -1217,7 +1229,7 @@ links to other files, Usenet articles, emails and much more. * Link format:: How links in Org-mode are formatted * Internal links:: Links to other places in the current file * External links:: URL-like links to the world -* Managing links:: Creating, inserting and following +* Handling links:: Creating, inserting and following * Search Options:: Linking to a specific location * Remember:: Org-trees store quick notes @@ -1255,24 +1267,26 @@ File: org, Node: Internal links, Next: External links, Prev: Link format, Up 4.2 Internal links ================== -If the link text does not look like a URL, links are considered to be -internal in the current file. Links such as `[[My Target]]' or `[[My -Target][Find my target]]' lead to a text search in the current file. -The link can be followed with `C-c C-o' when the cursor is on the link, -or with a mouse click (*note Managing links::). The preferred match -for such a link is a dedicated target: The same string in double -angular brackets. Targets may be located anywhere, often it is -convenient to put them into a comment line, for example +If the link does not look like a URL, it is considered to be internal in +the current file. Links such as `[[My Target]]' or `[[My Target][Find +my target]]' lead to a text search in the current file. The link can +be followed with `C-c C-o' when the cursor is on the link, or with a +mouse click (*note Handling links::). The preferred match for such a +link is a dedicated target: The same string in double angular brackets. +Targets may be located anywhere, often it is convenient to put them +into a comment line, for example # <> +In HTML export (*note HTML export::), such targets will become named +anchors for direct access through `http' links. + If no dedicated target exists, Org-mode will search for the words in -the link, often removing the need for a dedicated target. In the above -example the search would be for `my target'. Links starting with a -star like `*My Target' restrict the search to headlines. When -searching, Org-mode will first try an exact match, but then move on to -more and more lenient searches. For example, the link `[[*My -Targets]]' will find any of the following: +the link. In the above example the search would be for `my target'. +Links starting with a star like `*My Target' restrict the search to +headlines. When searching, Org-mode will first try an exact match, but +then move on to more and more lenient searches. For example, the link +`[[*My Targets]]' will find any of the following: ** My targets ** TODO my targets are bright @@ -1281,7 +1295,7 @@ Targets]]' will find any of the following: To insert a link targeting a headline, in-buffer completion can be used. Just type a star followed by a few optional letters into the buffer and press `M-'. All headlines in the current buffer will be -offered as completions. *Note Managing links::, for more commands +offered as completions. *Note Handling links::, for more commands creating links. Following a link pushes a mark onto Org-mode's own mark ring. You @@ -1323,7 +1337,7 @@ option `org-activate-links'. A CamelCase word then leads to a text search such that `CamelCaseLink' is equivalent to `[[camel case link]]'.  -File: org, Node: External links, Next: Managing links, Prev: Internal links, Up: Hyperlinks +File: org, Node: External links, Next: Handling links, Prev: Internal links, Up: Hyperlinks 4.3 External links ================== @@ -1363,9 +1377,9 @@ them as links. If spaces must be part of the link (for example in link, enclose them in angular brackets.  -File: org, Node: Managing links, Next: Search Options, Prev: External links, Up: Hyperlinks +File: org, Node: Handling links, Next: Search Options, Prev: External links, Up: Hyperlinks -4.4 Managing links +4.4 Handling links ================== Org-mode provides methods to create a link in the correct syntax, to @@ -1375,27 +1389,27 @@ insert it into an org-mode file, and to follow the link. Store a link to the current location. This is a _global_ command which can be used in any buffer to create a link. The link will be stored for later insertion into an Org-mode buffer (see below). - For VM, RMAIL, WANDERLUST, MH-E, GNUS and BBDB buffers, the link - will point to the current article/entry. For W3 and W3M buffers, - the link goes to the current URL. For Org-mode files, the current - headline is targeted. For any other files, the link will point to - the file, with a search string (*note Search Options::) pointing - to the contents of the current line. If there is an active - region, the selected words will form the basis of the search - string. The key binding `C-c l' is only a suggestion - see *Note - Installation and activation::. + For Org-mode files, if there is a `<>' at the cursor, the + link points to the target. Otherwise it points to the current + headline. For VM, RMAIL, WANDERLUST, MH-E, GNUS and BBDB buffers, + the link will indicate to the current article/entry. For W3 and + W3M buffers, the link goes to the current URL. For any other + files, the link will point to the file, with a search string + (*note Search Options::) pointing to the contents of the current + line. If there is an active region, the selected words will form + the basis of the search string. The key binding `C-c l' is only a + suggestion - see *Note Installation and activation::. `C-c C-l' Insert a link. This prompts for a link to be inserted into the buffer. You can just type a link, using text for an internal link, or one of the link type prefixes mentioned in the examples above. Through completion, all links stored during the current - session can be accessed. The link will be formatted as given in - the variable `org-link-format' and inserted into the buffer, along - with a descriptive text. Note that you don't have to use this - command to insert a link. Links in Org-mode are plain text, and - you can type or paste them straight into the buffer. By using - this command, the links are automatically enclosed in double + session can be accessed. The link will be inserted into the + buffer, along with a descriptive text. Note that you don't have + to use this command to insert a link. Links in Org-mode are plain + text, and you can type or paste them straight into the buffer. By + using this command, the links are automatically enclosed in double brackets, and you will be asked for the optional descriptive text. `C-u C-c C-l' @@ -1403,10 +1417,11 @@ insert it into an org-mode file, and to follow the link. file will be inserted and you may use file name completion to select the name of the file. The path to the file is inserted relative to the directory of the current org file, if the linked - file is in the current directory or in a subdirectory of it. - Otherwise an absolute path, if possible with `~/' for your home - directory is used. You can force an absolute path with two `C-u' - prefixes. + file is in the current directory or in a subdirectory of it, or if + the path is written relative to the current directory using `../'. + Otherwise an absolute path is used, if possible with `~/' for + your home directory. You can force an absolute path with two + `C-u' prefixes. `C-c C-l with cursor on existing link' When the cursor is on an existing link, `C-c C-l' allows to edit @@ -1445,7 +1460,7 @@ insert it into an org-mode file, and to follow the link. previously recorded positions.  -File: org, Node: Search Options, Next: Remember, Prev: Managing links, Up: Hyperlinks +File: org, Node: Search Options, Next: Remember, Prev: Handling links, Up: Hyperlinks 4.5 Search options in file links ================================ @@ -1467,7 +1482,9 @@ Here is what these options do. `My Target' Search for a link target `<>', or do a text search for `my target', similar to the search in internal links, see *Note - Internal links::. + Internal links::. In HTML export (*note HTML export::), such a + file link will become an html reference to the corresponding named + anchor in the linked file. `*My Target' In an Org-mode file, restrict search to headlines. @@ -1631,16 +1648,12 @@ The most important commands to work with TODO entries are: `C-c a t' Show the global TODO list. This collects the TODO items from all - agenda files (*note Agenda Views::) into a single buffer. The + agenda files (*note Agenda views::) into a single buffer. The 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. -``org-agenda-include-all-todo'' - If you would like to have all your TODO items listed as part of - your agenda, customize the variable `org-agenda-include-all-todo'. -  File: org, Node: Progress logging, Next: TODO extensions, Prev: TODO basics, Up: TODO items @@ -1657,7 +1670,7 @@ in the Org-mode buffer or `t' in the agenda buffer, a line `CLOSED: [timestamp]' will be inserted just after the headline. If you turn the entry back into a TODO item again through further state cycling, that line will be removed again. In the timeline (*note Timeline::) and in -the agenda (*note Weekly/Daily Agenda::), you can then use the `L' key +the agenda (*note Weekly/Daily agenda::), you can then use the `L' key to display the TODO items closed on each day, giving you an overview of what has been done on a day. @@ -1795,7 +1808,7 @@ headline, like this With its standard setup, Org-mode supports priorities `A', `B', and `C'. `A' is the highest priority. An entry without a cookie is treated as priority `B'. Priorities make a difference only in the -agenda (*note Weekly/Daily Agenda::). +agenda (*note Weekly/Daily agenda::). `C-c ,' Set the priority of the current item. The command prompts for a @@ -1835,11 +1848,14 @@ A time stamp is a specification of a date (possibly with time) in a special format, either `<2003-09-16 Tue>' or `<2003-09-16 Tue 09:39>'. A time stamp can appear anywhere in the headline or body of an org-tree entry. Its presence allows entries to be shown on specific dates in -the agenda (*note Weekly/Daily Agenda::). We distinguish: +the agenda (*note Weekly/Daily agenda::). We distinguish: TIMESTAMP - A simple time stamp just assigns a date/time to an item. In the - timeline and agenda displays, the headline of the entry will be + A simple time stamp just assigns a date/time to an item. This is + just like writing down an appointment in a paper agenda, or like + writing down an event in a diary, when you want to take not of + when something happened. In the timeline and agenda displays, the + headline of an entry associated with a plain time stamp will be shown exactly on that date. TIMERANGE @@ -1851,6 +1867,19 @@ TIMERANGE ** Meeting in Amsterdam <2004-08-23 Mon>--<2004-08-26 Thu> +SCHEDULED + If a time stamp is preceded by the word `SCHEDULED:', it means you + are planning to start working on that task on the given date. So + this is not about recording an event, but about planning your + work. The headline will be listed under the given date. In + addition, a reminder that the scheduled date has passed will be + present in the compilation for _today_, until the entry is marked + DONE. I.e., the task will automatically be forwarded until + completed. + + *** TODO Call Trillian for a date on New Years Eve. + SCHEDULED: <2004-12-25 Sat> + DEADLINE If a time stamp is preceded by the word `DEADLINE:', the task (most likely a TODO item) is supposed to be finished on that date, @@ -1863,14 +1892,6 @@ DEADLINE The editor in charge is DEADLINE: <2004-02-29 Sun> -SCHEDULED - If a time stamp is preceded by the word `SCHEDULED:', it means you - are planning to start working on that task on the given date. The - headline will be listed under the given date. In addition, a - reminder that the scheduled date has passed will be present in the - compilation for _today_, until the entry is marked DONE. I.e., the - task will automatically be forwarded. -  File: org, Node: Creating timestamps, Prev: Time stamps, Up: Timestamps @@ -1906,7 +1927,7 @@ format. `C-c C-o' Access the agenda for the date given by the time stamp at point - (*note Weekly/Daily Agenda::). + (*note Weekly/Daily agenda::). `C-c C-d' Insert `DEADLINE' keyword along with a stamp. @@ -1977,7 +1998,7 @@ date can be selected with the following commands: Choose date in calendar (only if nothing typed into minibuffer).  -File: org, Node: Tags, Next: Agenda Views, Prev: Timestamps, Up: Top +File: org, Node: Tags, Next: Agenda views, Prev: Timestamps, Up: Top 7 Tags ****** @@ -2074,7 +2095,7 @@ selects all lines tagged `:WORK:' or `:LAPTOP:'. The string `NIGHT'.  -File: org, Node: Agenda Views, Next: Exporting, Prev: Tags, Up: Top +File: org, Node: Agenda views, Next: Exporting, Prev: Tags, Up: Top 8 Agenda Views ************** @@ -2105,14 +2126,14 @@ edit these files remotely. * Agenda files:: Files being searched for agenda information * Agenda dispatcher:: Keyboard access to agenda views -* Weekly/Daily Agenda:: The calendar page with current tasks +* 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 * Timeline:: Time-sorted view for single file * Agenda commands:: Remote editing of org trees  -File: org, Node: Agenda files, Next: Agenda dispatcher, Prev: Agenda Views, Up: Agenda Views +File: org, Node: Agenda files, Next: Agenda dispatcher, Prev: Agenda views, Up: Agenda views 8.1 Agenda files ================ @@ -2148,7 +2169,7 @@ command will actually limit the command to the current file, and ignore `org-agenda-files' until the next dispatcher command.  -File: org, Node: Agenda dispatcher, Next: Weekly/Daily Agenda, Prev: Agenda files, Up: Agenda Views +File: org, Node: Agenda dispatcher, Next: Weekly/Daily agenda, Prev: Agenda files, Up: Agenda views 8.2 The agenda dispatcher ========================= @@ -2161,7 +2182,7 @@ accordingly. After pressing `C-c a', an additional letter is required to execute a command. The dispatcher offers the following default commands: `a' - Create the calendar-like agenda (*note Weekly/Daily Agenda::). + Create the calendar-like agenda (*note Weekly/Daily agenda::). `t / T' Create a list of all TODO items (*note Global TODO list::). @@ -2197,7 +2218,7 @@ containing the word `FIXME'. For more information, look at the documentation string of the variable `org-agenda-custom-commands'.  -File: org, Node: Weekly/Daily Agenda, Next: Global TODO list, Prev: Agenda dispatcher, Up: Agenda Views +File: org, Node: Weekly/Daily agenda, Next: Global TODO list, Prev: Agenda dispatcher, Up: Agenda views 8.3 The weekly/daily agenda =========================== @@ -2225,7 +2246,7 @@ buffer. The commands available in the Agenda buffer are listed in * Sorting of agenda items:: The order of things  -File: org, Node: Categories, Next: Time-of-day specifications, Prev: Weekly/Daily Agenda, Up: Weekly/Daily Agenda +File: org, Node: Categories, Next: Time-of-day specifications, Prev: Weekly/Daily agenda, Up: Weekly/Daily agenda 8.3.1 Categories ---------------- @@ -2242,7 +2263,7 @@ any text before the first CATEGORY line). The display in the agenda buffer looks best if the category is not longer than 10 characters.  -File: org, Node: Time-of-day specifications, Next: Calendar/Diary integration, Prev: Categories, Up: Weekly/Daily Agenda +File: org, Node: Time-of-day specifications, Next: Calendar/Diary integration, Prev: Categories, Up: Weekly/Daily agenda 8.3.2 Time-of-Day Specifications -------------------------------- @@ -2287,7 +2308,7 @@ timed entries are embedded in a time grid, like `org-agenda-time-grid'.  -File: org, Node: Calendar/Diary integration, Next: Sorting of agenda items, Prev: Time-of-day specifications, Up: Weekly/Daily Agenda +File: org, Node: Calendar/Diary integration, Next: Sorting of agenda items, Prev: Time-of-day specifications, Up: Weekly/Daily agenda 8.3.3 Calendar/Diary integration -------------------------------- @@ -2316,7 +2337,7 @@ to other calendars, respectively. `c' can be used to switch back and forth between calendar and agenda.  -File: org, Node: Sorting of agenda items, Prev: Calendar/Diary integration, Up: Weekly/Daily Agenda +File: org, Node: Sorting of agenda items, Prev: Calendar/Diary integration, Up: Weekly/Daily agenda 8.3.4 Sorting of agenda items ----------------------------- @@ -2336,7 +2357,7 @@ increments for overdue scheduled or deadline items. `org-agenda-sorting-strategy'.  -File: org, Node: Global TODO list, Next: Matching headline tags, Prev: Weekly/Daily Agenda, Up: Agenda Views +File: org, Node: Global TODO list, Next: Matching headline tags, Prev: Weekly/Daily agenda, Up: Agenda views 8.4 The global TODO list ======================== @@ -2346,7 +2367,7 @@ collected into a single place. `C-c a t' Show the global TODO list. This collects the TODO items from all - agenda files (*note Agenda Views::) into a single buffer. The + agenda files (*note Agenda views::) into a single buffer. The 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 @@ -2368,7 +2389,7 @@ TODO entry with a single key press. The commands available in the TODO list are described in *Note Agenda commands::.  -File: org, Node: Matching headline tags, Next: Timeline, Prev: Global TODO list, Up: Agenda Views +File: org, Node: Matching headline tags, Next: Timeline, Prev: Global TODO list, Up: Agenda views 8.5 Matching headline tags ========================== @@ -2393,7 +2414,7 @@ collect them into an agenda buffer. Agenda commands::.  -File: org, Node: Timeline, Next: Agenda commands, Prev: Matching headline tags, Up: Agenda Views +File: org, Node: Timeline, Next: Agenda commands, Prev: Matching headline tags, Up: Agenda views 8.6 Timeline for a single file ============================== @@ -2414,7 +2435,7 @@ The commands available in the timeline buffer are listed in *Note Agenda commands::.  -File: org, Node: Agenda commands, Prev: Timeline, Up: Agenda Views +File: org, Node: Agenda commands, Prev: Timeline, Up: Agenda views 8.7 Commands in the agenda buffer ================================= @@ -2607,7 +2628,7 @@ Quit and Exit  -File: org, Node: Exporting, Next: Miscellaneous, Prev: Agenda Views, Up: Top +File: org, Node: Exporting, Next: Miscellaneous, Prev: Agenda views, Up: Top 9 Exporting *********** @@ -2808,7 +2829,7 @@ formatted output. * Plain lists `-', `*' or `+' as bullet, or with `1.' or `2)' as enumerator will be recognized and transformed if the backend - supports lists. See *Note Plain Lists::. + supports lists. See *Note Plain lists::. * You can make words *bold*, /italic/, and _underlined_ @@ -2966,7 +2987,7 @@ file is visited again in a new Emacs session. corresponding variable is `org-startup-align-all-tables', with a default value `nil'. align align all tables - noalign don't align table on startup + noalign don't align tables on startup Here are the options for hiding leading stars in outline headings. The corresponding variables are `org-hide-leading-stars' and `org-odd-levels-only', both with a default setting `nil' (meaning @@ -2991,7 +3012,7 @@ file is visited again in a new Emacs session. line. `#+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+TEXT:, #+OPTIONS:' - These line provide setting for exporting files. For more details + These lines provide setting for exporting files. For more details see *Note Export options::.  @@ -3160,26 +3181,37 @@ File: org, Node: FAQ, Next: Interaction, Prev: TTY keys, Up: Miscellaneous 10.7 Frequently asked questions =============================== - 1. Org-mode seems to be a useful default mode for the various + 1. When I try to use Org-mode, I always get `(wrong-type-argument + keymapp nil)'. + This is a conflict with an outdated version of the `allout.el' + package which pretends to be also the standard outline-mode but is + not. This happens with older versions of `allout.el', for example + the one distributed with Emacs 21. Upgrade to Emacs 22 and this + problem will disappear. If for some reason you cannot do this, + make sure that org.el is loaded _before_ `allout.el', for example + by putting `(require 'org)' early enough into your `.emacs' file. + + 2. Org-mode seems to be a useful default mode for the various `README' files I have scattered through my directories. How do I turn it on for all `README' files? + (add-to-list 'auto-mode-alist '("README$" . org-mode)) - 2. Some of my links stopped working after I upgraded to a version + 3. Some of my links stopped working after I upgraded to a version 4.20 or later. Why is this, and how can I fix it? These must be links in plain text, containing white space, such as `bbdb:Richard Stallman'. You need to protect these links by putting double brackets around them, like `[[bbdb:Richard Stallman]]'. - 3. I see that Org-mode now creates links using the double bracket + 4. I see that Org-mode now creates links using the double bracket convention that hides the link part and the brackets, only showing the description part. How can I convert my old links to this new format? Execute once in each Org-mode file: `M-x org-upgrade-old-links'. - The replaces angular brackets with the link format. + This replaces angular brackets with the new link format. - 4. I don't care if you find the new bracket links great, I am + 5. I don't care if you find the new bracket links great, I am attached to the old style using angular brackets and no hiding of the link text. Please give them back to me, don't tell me it is not possible! @@ -3188,7 +3220,7 @@ File: org, Node: FAQ, Next: Interaction, Prev: TTY keys, Up: Miscellaneous (setq org-link-style 'plain org-link-format "<%s>") - 5. When I am executing shell links I always get a confirmation prompt + 6. When I am executing shell links I always get a confirmation prompt and need to type `yes ', thats 4 key presses! Can I get rid of this? The confirmation is there to protect you from unwantingly execute @@ -3201,19 +3233,19 @@ File: org, Node: FAQ, Next: Interaction, Prev: TTY keys, Up: Miscellaneous shell links. It is also possible to turn off this check entirely, but I do not recommend to do this. Be warned. - 6. All these stars are driving me mad, I just find the Emacs outlines + 7. All these stars are driving me mad, I just find the Emacs outlines unreadable. Can't you just put white space and a single star as a starter for headlines? See *Note Clean view::. - 7. I would like to have two windows on the same Org-mode file, but + 8. I would like to have two windows on the same Org-mode file, but with different outline visibility. Is that possible? In GNU Emacs, you may use _indirect buffers_ which do exactly this. See the documentation on the command `make-indirect-buffer'. In XEmacs, this is currently not possible because of the different outline implementation. - 8. When I export my TODO list, every TODO item becomes a separate + 9. When I export my TODO list, every TODO item becomes a separate section. How do I enforce these items to be exported as an itemized list? If you plan to use ASCII or HTML export, make sure things you want @@ -3231,35 +3263,35 @@ File: org, Node: FAQ, Next: Interaction, Prev: TTY keys, Up: Miscellaneous +OPTIONS: H:2; ... - 9. I would like to export only a subtree of my file to HTML. How? + 10. I would like to export only a subtree of my file to HTML. How? If you want to export a subtree, mark the subtree as region and then export. Marking can be done with `C-c @ C-x C-x', for example. - 10. Org-mode takes over the S-cursor keys. I also want to use + 11. Org-mode takes over the S-cursor keys. I also want to use CUA-mode, is there a way to fix this conflict? Yes, see *Note Interaction::. - 11. One of my table columns has started to fill up with `#ERROR'. + 12. One of my table columns has started to fill up with `#ERROR'. What is going on? Org-mode tried to compute the column from other fields using a formula stored in the `#+TBLFM:' line just below the table, and the evaluation of the formula fails. Fix the fields used in the formula, or fix the formula, or remove it! - 12. When I am in the last column of a table and just above a + 13. When I am in the last column of a table and just above a horizontal line in the table, pressing TAB creates a new table line before the horizontal line. How can I quickly move to the line below the horizontal line instead? Press (to get on the separator line) and then . Or configure the variable `org-table-tab-jumps-over-hlines'. - 13. How can I change the indentation of an entire table without fixing + 14. How can I change the indentation of an entire table without fixing every line by hand? The indentation of a table is set by the first line. So just fix the indentation of the first line and realign with . - 14. Is it possible to include entries from org-mode files into my + 15. Is it possible to include entries from org-mode files into my emacs diary? Since the org-mode agenda is much more powerful and can contain the diary (*note Calendar/Diary integration::), you should think twice @@ -3455,6 +3487,9 @@ Org-mode would not be what it is without your input. * Kevin Rogers contributed code to access VM files on remote hosts. + * Frank Ruell solved the mystery of the `keymapp nil' bug, a conflict + with `allout.el'. + * Philip Rooke created the Org-mode reference card and provided lots of feedback. @@ -3503,13 +3538,14 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * active region <2>: ASCII export. (line 9) * active region <3>: Built-in table editor. (line 165) -* active region: Structure editing. (line 46) -* agenda: Weekly/Daily Agenda. (line 6) +* active region: Structure editing. (line 51) +* agenda: Weekly/Daily agenda. (line 6) * agenda commands, custom: Agenda dispatcher. (line 6) * agenda dispatcher: Agenda dispatcher. (line 6) * agenda files, removing buffers: Agenda commands. (line 187) -* agenda views: Agenda Views. (line 6) +* agenda views: Agenda views. (line 6) * agenda, for single file: Timeline. (line 6) +* allout.el, conflict with: FAQ. (line 6) * angular brackets, around links: External links. (line 35) * applescript, for calendar update: iCalendar export. (line 38) * archive locations: Archiving. (line 13) @@ -3542,8 +3578,8 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * completion, of CamelCase links <1>: Completion. (line 6) * completion, of CamelCase links: CamelCase links. (line 6) * completion, of dictionary words: Completion. (line 6) -* completion, of file names: Managing links. (line 36) -* completion, of links: Managing links. (line 23) +* completion, of file names: Handling links. (line 36) +* completion, of links: Handling links. (line 24) * completion, of option keywords <1>: Completion. (line 6) * completion, of option keywords: Export options. (line 6) * Completion, of option keywords: Per file keywords. (line 17) @@ -3564,10 +3600,10 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * cutting, of subtrees: Structure editing. (line 6) * cycling, of TODO states: TODO basics. (line 13) * cycling, visibility: Visibility cycling. (line 6) -* dangerous commands: FAQ. (line 37) +* dangerous commands: FAQ. (line 48) * date stamps: Time stamps. (line 6) * date, reading in minibuffer: Creating timestamps. (line 68) -* DEADLINE keyword: Time stamps. (line 27) +* DEADLINE keyword: Time stamps. (line 43) * deadlines: Time stamps. (line 6) * demotion, of subtrees: Structure editing. (line 6) * diary entries, creating from agenda: Agenda commands. (line 145) @@ -3575,7 +3611,7 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top (line 6) * dictionary word completion: Completion. (line 6) * dispatching agenda commands: Agenda dispatcher. (line 6) -* document structure: Document Structure. (line 6) +* document structure: Document structure. (line 6) * DONE, final TODO keyword: Per file keywords. (line 20) * editing tables: Tables. (line 6) * editing, of table formulas: Editing/debugging formulas. @@ -3584,7 +3620,7 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * enhancing text: Enhancing text. (line 6) * evaluate time range: Creating timestamps. (line 63) * exporting: Exporting. (line 6) -* exporting a subtree: FAQ. (line 78) +* exporting a subtree: FAQ. (line 89) * exporting, not: Comment lines. (line 6) * extended TODO keywords: TODO extensions. (line 6) * external links: External links. (line 6) @@ -3592,14 +3628,14 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * feedback: Feedback. (line 6) * file links: External links. (line 6) * file links, searching: Search Options. (line 6) -* file name completion: Managing links. (line 36) +* file name completion: Handling links. (line 36) * files, adding to agenda list: Agenda files. (line 12) * filing subtrees: Archiving. (line 6) * fixed width: Enhancing text. (line 30) * fixed-width sections: Export options. (line 25) * folded, subtree visibility state: Visibility cycling. (line 10) * folding, sparse trees: Sparse trees. (line 6) -* following links: Managing links. (line 50) +* following links: Handling links. (line 51) * format specifier: Formula syntax. (line 34) * format, of links: Link format. (line 6) * formula editing: Editing/debugging formulas. @@ -3630,10 +3666,10 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * iCalendar export: iCalendar export. (line 6) * in-buffer settings: Summary of in-buffer settings. (line 6) -* indentation, of tables: FAQ. (line 102) -* indirect buffers: FAQ. (line 54) +* indentation, of tables: FAQ. (line 113) +* indirect buffers: FAQ. (line 65) * inheritance, of tags: Tag inheritance. (line 6) -* inserting links: Managing links. (line 23) +* inserting links: Handling links. (line 24) * installation: Installation and activation. (line 6) * internal links: Internal links. (line 6) @@ -3642,20 +3678,21 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * jumping, to headlines: Motion. (line 6) * keybindings, global: Installation and activation. (line 6) +* keymapp nil error: FAQ. (line 6) * keyword options: Per file keywords. (line 6) * linebreak preservation: Export options. (line 25) -* link completion: Managing links. (line 23) +* link completion: Handling links. (line 24) * link format: Link format. (line 6) * links, external: External links. (line 6) * links, internal: Internal links. (line 6) -* links, returning to: Managing links. (line 76) +* links, returning to: Handling links. (line 77) * lists, hand-formatted: Enhancing text. (line 11) -* lists, ordered: Plain Lists. (line 6) -* lists, plain: Plain Lists. (line 6) +* lists, ordered: Plain lists. (line 6) +* lists, plain: Plain lists. (line 6) * logging, of progress: Progress logging. (line 6) * maintainer: Feedback. (line 6) -* make-indirect-buffer: FAQ. (line 54) -* mark ring: Managing links. (line 72) +* make-indirect-buffer: FAQ. (line 65) +* mark ring: Handling links. (line 73) * marking characters, tables: Advanced features. (line 34) * matching, of tags: Matching headline tags. (line 6) @@ -3673,8 +3710,8 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * option keyword completion: Completion. (line 6) * options, for customization: Customization. (line 6) * options, for export: Export options. (line 6) -* ordered lists: Plain Lists. (line 6) -* org-agenda, command: Weekly/Daily Agenda. (line 9) +* ordered lists: Plain lists. (line 6) +* org-agenda, command: Weekly/Daily agenda. (line 9) * org-mode, turning on: Installation and activation. (line 28) * org-mouse.el: Interaction. (line 8) @@ -3686,7 +3723,7 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * packages, interaction with other: Interaction. (line 6) * pasting, of subtrees: Structure editing. (line 6) * per file keywords: Per file keywords. (line 6) -* plain lists: Plain Lists. (line 6) +* plain lists: Plain lists. (line 6) * plain text external links: External links. (line 35) * printing sparse trees: Sparse trees. (line 39) * priorities: Priorities. (line 6) @@ -3701,18 +3738,18 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * region, active <2>: ASCII export. (line 9) * region, active <3>: Built-in table editor. (line 165) -* region, active: Structure editing. (line 46) +* region, active: Structure editing. (line 51) * remember.el <1>: Interaction. (line 40) * remember.el: Remember. (line 6) * richer text: Enhancing text. (line 6) * RMAIL links: External links. (line 6) -* SCHEDULED keyword: Time stamps. (line 39) +* SCHEDULED keyword: Time stamps. (line 30) * scheduling: Time stamps. (line 6) * search option in file links: Search Options. (line 6) * section-numbers: Export options. (line 25) * setting tags: Setting tags. (line 6) * SHELL links: External links. (line 6) -* shell links, confirmation: FAQ. (line 37) +* shell links, confirmation: FAQ. (line 48) * show all, command: Visibility cycling. (line 27) * show all, global visibility state: Visibility cycling. (line 19) * show hidden text: Visibility cycling. (line 6) @@ -3726,9 +3763,9 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * special keywords: Summary of in-buffer settings. (line 6) * spreadsheet capabilities: Table calculations. (line 6) -* storing links: Managing links. (line 9) +* storing links: Handling links. (line 9) * structure editing: Structure editing. (line 6) -* structure of document: Document Structure. (line 6) +* structure of document: Document structure. (line 6) * subtree visibility states: Visibility cycling. (line 10) * subtree, cut and paste: Structure editing. (line 6) * subtree, subtree visibility state: Visibility cycling. (line 10) @@ -3759,7 +3796,7 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * time, reading in minibuffer: Creating timestamps. (line 68) * time-sorted view: Timeline. (line 6) * timeline, single file: Timeline. (line 6) -* timerange: Time stamps. (line 18) +* timerange: Time stamps. (line 21) * timestamp: Time stamps. (line 12) * timestamps, creating: Creating timestamps. (line 6) * TODO items: TODO items. (line 6) @@ -3771,7 +3808,7 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * transient-mark-mode <2>: ASCII export. (line 9) * transient-mark-mode <3>: Built-in table editor. (line 165) -* transient-mark-mode: Structure editing. (line 46) +* transient-mark-mode: Structure editing. (line 51) * trees, sparse: Sparse trees. (line 6) * trees, visibility: Visibility cycling. (line 6) * tty keybindings: TTY keys. (line 6) @@ -3813,7 +3850,7 @@ File: org, Node: Key Index, Prev: Index, Up: Top * <1>: Agenda commands. (line 35) * <2>: Built-in table editor. (line 57) -* <3>: Plain Lists. (line 37) +* <3>: Plain lists. (line 38) * : Visibility cycling. (line 10) * > <1>: Agenda commands. (line 140) * >: Creating timestamps. (line 76) @@ -3824,8 +3861,8 @@ File: org, Node: Key Index, Prev: Index, Up: Top * C-,: Agenda files. (line 18) * C-c !: Creating timestamps. (line 21) * C-c $: Archiving. (line 9) -* C-c %: Managing links. (line 72) -* C-c &: Managing links. (line 76) +* C-c %: Handling links. (line 73) +* C-c &: Handling links. (line 77) * C-c ' <1>: Editing/debugging formulas. (line 20) * C-c ': Built-in table editor. @@ -3858,7 +3895,7 @@ File: org, Node: Key Index, Prev: Index, Up: Top (line 96) * C-c `: Built-in table editor. (line 181) -* C-c a a: Weekly/Daily Agenda. (line 9) +* C-c a a: Weekly/Daily agenda. (line 9) * C-c a C: Agenda dispatcher. (line 30) * C-c a M: Matching headline tags. (line 15) @@ -3879,14 +3916,14 @@ File: org, Node: Key Index, Prev: Index, Up: Top (line 16) * C-c C-c <5>: Built-in table editor. (line 54) -* C-c C-c: Plain Lists. (line 61) +* C-c C-c: Plain lists. (line 68) * C-c C-d: Creating timestamps. (line 37) * C-c C-f: Motion. (line 12) * C-c C-j: Motion. (line 21) -* C-c C-l: Managing links. (line 23) +* C-c C-l: Handling links. (line 24) * C-c C-n: Motion. (line 8) * C-c C-o <1>: Creating timestamps. (line 33) -* C-c C-o: Managing links. (line 50) +* C-c C-o: Handling links. (line 51) * C-c C-p: Motion. (line 9) * C-c C-q <1>: Editing/debugging formulas. (line 20) @@ -3903,30 +3940,30 @@ File: org, Node: Key Index, Prev: Index, Up: Top * C-c C-x c: iCalendar export. (line 20) * C-c C-x C-c: Agenda commands. (line 177) * C-c C-x C-i: iCalendar export. (line 15) -* C-c C-x C-k: Structure editing. (line 31) +* C-c C-x C-k: Structure editing. (line 36) * C-c C-x C-w <1>: Built-in table editor. (line 108) -* C-c C-x C-w: Structure editing. (line 31) +* C-c C-x C-w: Structure editing. (line 36) * C-c C-x C-x: XML export. (line 10) * C-c C-x C-y <1>: Built-in table editor. (line 112) -* C-c C-x C-y: Structure editing. (line 38) +* C-c C-x C-y: Structure editing. (line 43) * C-c C-x h: HTML export. (line 10) * C-c C-x i: iCalendar export. (line 13) * C-c C-x M-w <1>: Built-in table editor. (line 105) -* C-c C-x M-w: Structure editing. (line 35) +* C-c C-x M-w: Structure editing. (line 40) * C-c C-x t: Export options. (line 13) * C-c C-x v: Sparse trees. (line 39) * C-c C-y: Creating timestamps. (line 63) -* C-c l: Managing links. (line 9) +* C-c l: Handling links. (line 9) * C-c |: Built-in table editor. (line 40) * C-c ~: table.el. (line 18) * C-u C-c .: Creating timestamps. (line 16) * C-u C-c =: Built-in table editor. (line 139) -* C-u C-c C-l: Managing links. (line 36) +* C-u C-c C-l: Handling links. (line 36) * D: Agenda commands. (line 66) * d: Agenda commands. (line 63) * f: Agenda commands. (line 44) @@ -3940,12 +3977,12 @@ File: org, Node: Key Index, Prev: Index, Up: Top (line 82) * M- <1>: Built-in table editor. (line 72) -* M-: Structure editing. (line 13) -* M- <1>: Plain Lists. (line 42) +* M-: Structure editing. (line 18) +* M- <1>: Plain lists. (line 43) * M-: Structure editing. (line 6) * M- <1>: Built-in table editor. (line 72) -* M-: Structure editing. (line 16) +* M-: Structure editing. (line 21) * M- <1>: Completion. (line 10) * M- <2>: Setting tags. (line 6) * M-: Per file keywords. (line 17) @@ -3953,30 +3990,30 @@ File: org, Node: Key Index, Prev: Index, Up: Top (line 82) * M-S- <1>: Built-in table editor. (line 89) -* M-S- <2>: Plain Lists. (line 46) -* M-S-: Structure editing. (line 28) +* M-S- <2>: Plain lists. (line 53) +* M-S-: Structure editing. (line 33) * M-S- <1>: Creating timestamps. (line 97) * M-S- <2>: Built-in table editor. (line 76) -* M-S- <3>: Plain Lists. (line 52) -* M-S-: Structure editing. (line 19) -* M-S-: Structure editing. (line 10) +* M-S- <3>: Plain lists. (line 59) +* M-S-: Structure editing. (line 24) +* M-S-: Structure editing. (line 15) * M-S- <1>: Creating timestamps. (line 94) * M-S- <2>: Built-in table editor. (line 79) -* M-S- <3>: Plain Lists. (line 52) -* M-S-: Structure editing. (line 22) +* M-S- <3>: Plain lists. (line 59) +* M-S-: Structure editing. (line 27) * M-S- <1>: Built-in table editor. (line 86) -* M-S- <2>: Plain Lists. (line 46) -* M-S-: Structure editing. (line 25) +* M-S- <2>: Plain lists. (line 53) +* M-S-: Structure editing. (line 30) * mouse-1 <1>: Agenda commands. (line 35) * mouse-1 <2>: Creating timestamps. (line 79) -* mouse-1: Managing links. (line 64) +* mouse-1: Handling links. (line 65) * mouse-2 <1>: Agenda commands. (line 35) -* mouse-2: Managing links. (line 64) +* mouse-2: Handling links. (line 65) * mouse-3 <1>: Agenda commands. (line 28) -* mouse-3: Managing links. (line 69) +* mouse-3: Handling links. (line 70) * n: Agenda commands. (line 19) * o: Agenda commands. (line 57) * P: Agenda commands. (line 115) @@ -4011,97 +4048,97 @@ Tag Table: Node: Top959 Node: Introduction7444 Node: Summary7758 -Node: Installation and activation9870 -Node: Feedback11539 -Node: Document Structure12325 -Node: Outlines13091 -Node: Headlines13751 -Node: Visibility cycling14374 -Node: Motion15570 -Node: Structure editing16354 -Node: Archiving18097 -Node: Sparse trees18957 -Ref: Sparse trees-Footnote-120986 -Ref: Sparse trees-Footnote-221078 -Node: Plain Lists21192 -Ref: Plain Lists-Footnote-123948 -Node: Tables24305 -Node: Built-in table editor24853 -Node: Narrow columns32466 -Ref: Narrow columns-Footnote-134399 -Node: Table calculations34445 -Node: Formula syntax35621 -Ref: Formula syntax-Footnote-138550 -Node: Column formulas38849 -Node: Advanced features40611 -Node: Named-field formulas43866 -Node: Editing/debugging formulas44506 -Node: Appetizer46264 -Node: orgtbl-mode47366 -Node: table.el47857 -Node: Hyperlinks48834 -Node: Link format49468 -Node: Internal links50765 -Node: Radio targets52655 -Node: CamelCase links53370 -Node: External links53868 -Node: Managing links55793 -Node: Search Options59777 -Ref: Search Options-Footnote-161097 -Node: Remember61178 -Ref: Remember-Footnote-165044 -Node: TODO items65168 -Node: TODO basics66091 -Node: Progress logging67606 -Node: TODO extensions68392 -Node: Workflow states69192 -Node: TODO types70060 -Ref: TODO types-Footnote-171718 -Node: Per file keywords71800 -Ref: Per file keywords-Footnote-173253 -Node: Priorities73481 -Node: Timestamps74690 -Node: Time stamps75011 -Node: Creating timestamps77026 -Node: Tags80155 -Node: Tag inheritance80890 -Node: Setting tags81827 -Node: Tag searches82789 -Node: Agenda Views83998 -Node: Agenda files85537 -Ref: Agenda files-Footnote-186497 -Ref: Agenda files-Footnote-286646 -Node: Agenda dispatcher86838 -Node: Weekly/Daily Agenda88968 -Node: Categories90103 -Node: Time-of-day specifications90751 -Node: Calendar/Diary integration92727 -Node: Sorting of agenda items94104 -Node: Global TODO list94936 -Node: Matching headline tags96351 -Node: Timeline97294 -Node: Agenda commands98167 -Node: Exporting103423 -Node: ASCII export104553 -Node: HTML export105375 -Node: XML export107123 -Node: iCalendar export107490 -Node: Text interpretation109312 -Node: Comment lines109789 -Node: Enhancing text110258 -Node: Export options112089 -Node: Miscellaneous113691 -Node: Completion114449 -Node: Customization115445 -Node: Summary of in-buffer settings116052 -Node: The very busy C-c C-c key118811 -Node: Clean view120216 -Node: TTY keys122793 -Node: FAQ124394 -Node: Interaction130708 -Node: Bugs133575 -Node: Acknowledgments135529 -Node: Index138527 -Node: Key Index159605 +Node: Installation and activation9866 +Node: Feedback11535 +Node: Document structure12321 +Node: Outlines13087 +Node: Headlines13747 +Node: Visibility cycling14370 +Node: Motion15566 +Node: Structure editing16350 +Node: Archiving18459 +Node: Sparse trees19319 +Ref: Sparse trees-Footnote-121348 +Ref: Sparse trees-Footnote-221440 +Node: Plain lists21555 +Ref: Plain lists-Footnote-124849 +Node: Tables25206 +Node: Built-in table editor25754 +Node: Narrow columns33367 +Ref: Narrow columns-Footnote-135306 +Node: Table calculations35352 +Node: Formula syntax36528 +Ref: Formula syntax-Footnote-139457 +Node: Column formulas39756 +Node: Advanced features41518 +Node: Named-field formulas44773 +Node: Editing/debugging formulas45413 +Node: Appetizer47171 +Node: orgtbl-mode48273 +Node: table.el48764 +Node: Hyperlinks49741 +Node: Link format50375 +Node: Internal links51672 +Node: Radio targets53622 +Node: CamelCase links54337 +Node: External links54835 +Node: Handling links56760 +Node: Search Options60853 +Ref: Search Options-Footnote-162323 +Node: Remember62404 +Ref: Remember-Footnote-166270 +Node: TODO items66394 +Node: TODO basics67317 +Node: Progress logging68658 +Node: TODO extensions69444 +Node: Workflow states70244 +Node: TODO types71112 +Ref: TODO types-Footnote-172770 +Node: Per file keywords72852 +Ref: Per file keywords-Footnote-174305 +Node: Priorities74533 +Node: Timestamps75742 +Node: Time stamps76063 +Node: Creating timestamps78491 +Node: Tags81620 +Node: Tag inheritance82355 +Node: Setting tags83292 +Node: Tag searches84254 +Node: Agenda views85463 +Node: Agenda files87002 +Ref: Agenda files-Footnote-187962 +Ref: Agenda files-Footnote-288111 +Node: Agenda dispatcher88303 +Node: Weekly/Daily agenda90433 +Node: Categories91568 +Node: Time-of-day specifications92216 +Node: Calendar/Diary integration94192 +Node: Sorting of agenda items95569 +Node: Global TODO list96401 +Node: Matching headline tags97816 +Node: Timeline98759 +Node: Agenda commands99632 +Node: Exporting104888 +Node: ASCII export106018 +Node: HTML export106840 +Node: XML export108588 +Node: iCalendar export108955 +Node: Text interpretation110777 +Node: Comment lines111254 +Node: Enhancing text111723 +Node: Export options113554 +Node: Miscellaneous115156 +Node: Completion115914 +Node: Customization116910 +Node: Summary of in-buffer settings117517 +Node: The very busy C-c C-c key120278 +Node: Clean view121683 +Node: TTY keys124260 +Node: FAQ125861 +Node: Interaction132763 +Node: Bugs135630 +Node: Acknowledgments137584 +Node: Index140679 +Node: Key Index161903  End Tag Table diff --git a/org.el b/org.el index 936f8619f..36836fe6a 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.24 +;; Version: 4.26 ;; ;; This file is part of GNU Emacs. ;; @@ -79,8 +79,17 @@ ;; excellent reference card made by Philip Rooke. This card can be found ;; in the etc/ directory of Emacs 22. ;; -;; Changes since version 4.00: +;; Changes since version 4.10: ;; --------------------------- +;; Version 4.26 +;; - Bug fixes. +;; +;; Version 4.25 +;; - Revision of the font-lock faces section, with better tty support. +;; - TODO keywords in Agenda buffer are fontified. +;; - Export converts links between .org files to links between .html files. +;; - Better support for bold/italic/underline emphasis. +;; ;; Version 4.24 ;; - Bug fixes. ;; @@ -113,60 +122,6 @@ ;; `org-time-stamp-rounding-minutes'. ;; - Bug fixes (there are *always* more bugs). ;; -;; Version 4.10 -;; - Bug fixes. -;; -;; Version 4.09 -;; - Bug fixes. -;; - Small improvements to font-lock support. -;; - MHE support finalized. -;; -;; Version 4.08 -;; - Bug fixes. -;; - Improved MHE support -;; -;; Version 4.07 -;; - Bug fixes. -;; - Leading stars in headlines can be hidden, so make the outline look -;; cleaner. -;; - Mouse-1 can be used to follow links. -;; -;; Version 4.06 -;; - HTML exporter treats targeted internal links. -;; - Bug fixes. -;; -;; Version 4.05 -;; - Changes to internal link system (thanks to David Wainberg for ideas). -;; - in-file links: [[Search String]] instead of -;; - automatic links to "radio targets". -;; - CamelCase not longer active by default, configure org-activate-camels -;; if you want to turn it back on. -;; - After following a link, `C-c &' jumps back to it. -;; - MH-E link support (thanks to Thomas Baumann). -;; - Special table lines are no longer exported. -;; - Bug fixes and minor improvements. -;; -;; Version 4.04 -;; - Cleanup tags display in agenda. -;; - Bug fixes. -;; -;; Version 4.03 -;; - Table alignment fixed for use with wide characters. -;; - `C-c -' leaves cursor in current table line. -;; - The current TAG can be incorporated into the agenda prefix. -;; See option `org-agenda-prefix-format' for details. -;; -;; Version 4.02 -;; - Minor bug fixes and improvements around tag searches. -;; - XEmacs compatibility fixes. -;; -;; Version 4.01 -;; - Tags can also be set remotely from agenda buffer. -;; - Boolean logic for tag searches. -;; - Additional agenda commands can be configured through the variable -;; `org-agenda-custom-commands'. -;; - Minor bug fixes. -;; ;;; Code: (eval-when-compile @@ -182,7 +137,7 @@ ;;; Customization variables -(defvar org-version "4.24" +(defvar org-version "4.26" "The version number of the file org.el.") (defun org-version () (interactive) @@ -192,7 +147,7 @@ ;; of outline.el. (defconst org-noutline-p (featurep 'noutline) "Are we using the new outline mode?") -(defconst org-xemacs-p (featurep 'xemacs)) +(defconst org-xemacs-p (featurep 'xemacs)) ; not used by org.el itself (defconst org-format-transports-properties-p (let ((x "a")) (add-text-properties 0 1 '(test t) x) @@ -1829,6 +1784,18 @@ you can \"misuse\" it to add arbitrary text to the header." :group 'org-export-html :type 'string) +(defcustom org-export-html-link-org-files-as-html t + "Non-nil means, make file links to `file.org' point to `file.html'. +When org-mode is exporting an org-mode file to HTML, links to +non-html files are directly put into a href tag in HTML. +However, links to other Org-mode files (recognized by the +extension `.org.) should become links to the corresponding html +file, assuming that the linked org-mode file will also be +converted to HTML. +When nil, the links still point to the plain `.org' file." + :group 'org-export-html + :type 'boolean) + (defcustom org-export-html-inline-images t "Non-nil means, inline images into exported HTML pages. The link will still be to the original location of the image file. @@ -1942,205 +1909,246 @@ Changing this variable requires a restart of Emacs to take effect." :tag "Org Faces" :group 'org-font-lock) +(defun org-compatible-face (specs) + "Make a compatible face specification. +XEmacs and Emacs 21 do not know about the `min-colors' attribute. +For them we convert a (min-colors 8) entry to a `tty' entry and move it +to the top of the list. The `min-colors' attribute will be removed from +any other entries, and any resulting duplicates will be removed entirely." + (if (or (featurep 'xemacs) (< emacs-major-version 22)) + (let (r e a) + (while (setq e (pop specs)) + (cond + ((memq (car e) '(t default)) (push e r)) + ((setq a (member '(min-colors 8) (car e))) + (nconc r (list (cons (cons '(type tty) (delq (car a) (car e))) + (cdr e))))) + ((setq a (assq 'min-colors (car e))) + (setq e (cons (delq a (car e)) (cdr e))) + (or (assoc (car e) r) (push e r))) + (t (or (assoc (car e) r) (push e r))))) + (nreverse r)) + specs)) + (defface org-hide - '( - (((type tty) (class color)) (:foreground "white")) - (((class color) (background light)) (:foreground "white")) - (((class color) (background dark)) (:foreground "black")) - (t (:inverse-video nil))) - "Face used for level 1 headlines." + '((((background light)) (:foreground "white")) + (((background dark)) (:foreground "black"))) + "Face used to hide leading stars in headlines. +The forground color of this face should be equal to the background +color of the frame." :group 'org-faces) (defface org-level-1 ;; font-lock-function-name-face - '((((type tty) (class color)) (:foreground "blue" :weight bold)) - (((class color) (background light)) (:foreground "Blue")) - (((class color) (background dark)) (:foreground "LightSkyBlue")) - (t (:inverse-video t :bold t))) + (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 level 1 headlines." :group 'org-faces) (defface org-level-2 ;; font-lock-variable-name-face - '((((type tty) (class color)) (:foreground "yellow" :weight light)) - (((class color) (background light)) (:foreground "DarkGoldenrod")) - (((class color) (background dark)) (:foreground "LightGoldenrod")) - (t (:bold t :italic t))) + (org-compatible-face + '((((class color) (min-colors 16) (background light)) (:foreground "DarkGoldenrod")) + (((class color) (min-colors 16) (background dark)) (:foreground "LightGoldenrod")) + (((class color) (min-colors 8) (background light)) (:foreground "yellow")) + (((class color) (min-colors 8) (background dark)) (:foreground "yellow" :bold t)) + (t (:bold t)))) "Face used for level 2 headlines." :group 'org-faces) (defface org-level-3 ;; font-lock-keyword-face - '((((type tty) (class color)) (:foreground "cyan" :weight bold)) - (((class color) (background light)) (:foreground "Purple")) - (((class color) (background dark)) (:foreground "Cyan")) - (t (:bold t))) + (org-compatible-face + '((((class color) (min-colors 88) (background light)) (:foreground "Purple")) + (((class color) (min-colors 88) (background dark)) (:foreground "Cyan1")) + (((class color) (min-colors 16) (background light)) (:foreground "Purple")) + (((class color) (min-colors 16) (background dark)) (:foreground "Cyan")) + (((class color) (min-colors 8) (background light)) (:foreground "purple" :bold t)) + (((class color) (min-colors 8) (background dark)) (:foreground "cyan" :bold t)) + (t (:bold t)))) "Face used for level 3 headlines." :group 'org-faces) (defface org-level-4 ;; font-lock-comment-face - '((((type tty pc) (class color) (background light)) (:foreground "red")) - (((type tty pc) (class color) (background dark)) (:foreground "red1")) - (((class color) (background light)) (:foreground "Firebrick")) - (((class color) (background dark)) (:foreground "chocolate1")) - (t (:bold t :italic t))) + (org-compatible-face + '((((class color) (min-colors 88) (background light)) (:foreground "Firebrick")) + (((class color) (min-colors 88) (background dark)) (:foreground "chocolate1")) + (((class color) (min-colors 16) (background light)) (:foreground "red")) + (((class color) (min-colors 16) (background dark)) (:foreground "red1")) + (((class color) (min-colors 8) (background light)) (:foreground "red" :bold t)) + (((class color) (min-colors 8) (background dark)) (:foreground "red" :bold t)) + (t (:bold t)))) "Face used for level 4 headlines." :group 'org-faces) (defface org-level-5 ;; font-lock-type-face - '((((type tty) (class color)) (:foreground "green")) - (((class color) (background light)) (:foreground "ForestGreen")) - (((class color) (background dark)) (:foreground "PaleGreen")) - (t (:bold t :underline t))) + (org-compatible-face + '((((class color) (min-colors 16) (background light)) (:foreground "ForestGreen")) + (((class color) (min-colors 16) (background dark)) (:foreground "PaleGreen")) + (((class color) (min-colors 8)) (:foreground "green")))) "Face used for level 5 headlines." :group 'org-faces) (defface org-level-6 ;; font-lock-constant-face - '((((type tty) (class color)) (:foreground "magenta")) - (((class color) (background light)) (:foreground "CadetBlue")) - (((class color) (background dark)) (:foreground "Aquamarine")) - (t (:bold t :underline t))) + (org-compatible-face + '((((class color) (min-colors 16) (background light)) (:foreground "CadetBlue")) + (((class color) (min-colors 16) (background dark)) (:foreground "Aquamarine")) + (((class color) (min-colors 8)) (:foreground "magenta")))) "Face used for level 6 headlines." :group 'org-faces) (defface org-level-7 ;; font-lock-builtin-face - '((((type tty) (class color)) (:foreground "blue" :weight light)) - (((class color) (background light)) (:foreground "Orchid")) - (((class color) (background dark)) (:foreground "LightSteelBlue")) - (t (:bold t))) + (org-compatible-face + '((((class color) (min-colors 16) (background light)) (:foreground "Orchid")) + (((class color) (min-colors 16) (background dark)) (:foreground "LightSteelBlue")) + (((class color) (min-colors 8)) (:foreground "blue")))) ;; FIXME: for dark bg? "Face used for level 7 headlines." :group 'org-faces) (defface org-level-8 ;; font-lock-string-face - '((((type tty) (class color)) (:foreground "green")) - (((class color) (background light)) (:foreground "RosyBrown")) - (((class color) (background dark)) (:foreground "LightSalmon")) - (t (:italic t))) + (org-compatible-face + '((((class color) (min-colors 16) (background light)) (:foreground "RosyBrown")) + (((class color) (min-colors 16) (background dark)) (:foreground "LightSalmon")) + (((class color) (min-colors 8)) (:foreground "green")))) "Face used for level 8 headlines." :group 'org-faces) (defface org-special-keyword ;; font-lock-string-face - '((((type tty) (class color)) (:foreground "green")) - (((class color) (background light)) (:foreground "RosyBrown")) - (((class color) (background dark)) (:foreground "LightSalmon")) - (t (:italic t))) + (org-compatible-face + '((((class color) (min-colors 16) (background light)) (:foreground "RosyBrown")) + (((class color) (min-colors 16) (background dark)) (:foreground "LightSalmon")) + (t (:italic t)))) "Face used for special keywords." :group 'org-faces) (defface org-warning ;; font-lock-warning-face - '((((type tty) (class color)) (:foreground "red")) - (((class color) (background light)) (:foreground "Red" :bold t)) - (((class color) (background dark)) (:foreground "Red1" :bold t)) -; (((class color) (background dark)) (:foreground "Pink" :bold t)) - (t (:inverse-video t :bold t))) + (org-compatible-face + '((((class color) (min-colors 16) (background light)) (:foreground "Red1" :bold t)) + (((class color) (min-colors 16) (background dark)) (:foreground "Pink" :bold t)) + (((class color) (min-colors 8) (background light)) (:foreground "red" :bold t)) + (((class color) (min-colors 8) (background dark)) (:foreground "red" :bold t)) + (t (:bold t)))) "Face for deadlines and TODO keywords." :group 'org-faces) (defface org-headline-done ;; font-lock-string-face - '((((type tty) (class color)) (:foreground "green")) - (((class color) (background light)) (:foreground "RosyBrown")) - (((class color) (background dark)) (:foreground "LightSalmon")) - (t (:italic t))) - "Face used to indicate that a headline is DONE. See also the variable -`org-fontify-done-headline'." - :group 'org-faces) - -;; Inheritance does not work for xemacs. So we just copy... - -(defface org-deadline-announce - '((((type tty) (class color)) (:foreground "blue" :weight bold)) - (((class color) (background light)) (:foreground "Blue")) - (((class color) (background dark)) (:foreground "LightSkyBlue")) - (t (:inverse-video t :bold t))) - "Face for upcoming deadlines." - :group 'org-faces) - -(defface org-scheduled-today - '((((type tty) (class color)) (:foreground "green")) - (((class color) (background light)) (:foreground "DarkGreen")) - (((class color) (background dark)) (:foreground "PaleGreen")) - (t (:bold t :underline t))) - "Face for items scheduled for a certain day." - :group 'org-faces) - -(defface org-scheduled-previously - '((((type tty pc) (class color) (background light)) (:foreground "red")) - (((type tty pc) (class color) (background dark)) (:foreground "red1")) - (((class color) (background light)) (:foreground "Firebrick")) - (((class color) (background dark)) (:foreground "chocolate1")) - (t (:bold t :italic t))) - "Face for items scheduled previously, and not yet done." - :group 'org-faces) - -(defface org-formula - '((((type tty pc) (class color) (background light)) (:foreground "red")) - (((type tty pc) (class color) (background dark)) (:foreground "red1")) - (((class color) (background light)) (:foreground "Firebrick")) - (((class color) (background dark)) (:foreground "chocolate1")) - (t (:bold t :italic t))) - "Face for formulas." + (org-compatible-face + '((((class color) (min-colors 16) (background light)) (:foreground "RosyBrown")) + (((class color) (min-colors 16) (background dark)) (:foreground "LightSalmon")) + (((class color) (min-colors 8) (background light)) (:bold nil)))) + "Face used to indicate that a headline is DONE. +This face is only used if `org-fontify-done-headline' is set." :group 'org-faces) (defface org-link - '((((type tty) (class color)) (:foreground "cyan" :weight bold)) - (((class color) (background light)) (:foreground "Purple" :underline t)) + '((((class color) (background light)) (:foreground "Purple" :underline t)) (((class color) (background dark)) (:foreground "Cyan" :underline t)) - (t (:bold t))) + (t (:underline t))) "Face for links." :group 'org-faces) (defface org-date - '((((type tty) (class color)) (:foreground "cyan" :weight bold)) - (((class color) (background light)) (:foreground "Purple" :underline t)) + '((((class color) (background light)) (:foreground "Purple" :underline t)) (((class color) (background dark)) (:foreground "Cyan" :underline t)) - (t (:bold t))) + (t (:underline t))) "Face for links." :group 'org-faces) (defface org-tag - '((((type tty) (class color)) (:weight bold)) - (((class color) (background light)) (:weight bold)) - (((class color) (background dark)) (:weight bold)) - (t (:bold t))) + '((t (:bold t))) "Face for tags." :group 'org-faces) (defface org-todo ;; font-lock-warning-face - '((((type tty) (class color)) (:foreground "red")) - (((class color) (background light)) (:foreground "Red" :bold t)) - (((class color) (background dark)) (:foreground "Red1" :bold t)) -; (((class color) (background dark)) (:foreground "Pink" :bold t)) - (t (:inverse-video t :bold t))) + (org-compatible-face + '((((class color) (min-colors 16) (background light)) (:foreground "Red1" :bold t)) + (((class color) (min-colors 16) (background dark)) (:foreground "Pink" :bold t)) + (((class color) (min-colors 8) (background light)) (:foreground "red" :bold t)) + (((class color) (min-colors 8) (background dark)) (:foreground "red" :bold t)) + (t (:inverse-video t :bold t)))) "Face for TODO keywords." :group 'org-faces) (defface org-done ;; font-lock-type-face - '((((type tty) (class color)) (:foreground "green")) - (((class color) (background light)) (:foreground "ForestGreen" :bold t)) - (((class color) (background dark)) (:foreground "PaleGreen" :bold t)) - (t (:bold t :underline t))) + (org-compatible-face + '((((class color) (min-colors 16) (background light)) (:foreground "ForestGreen")) + (((class color) (min-colors 16) (background dark)) (:foreground "PaleGreen")) + (((class color) (min-colors 8)) (:foreground "green")) + (t (:bold t)))) "Face used for DONE." :group 'org-faces) (defface org-table ;; font-lock-function-name-face - '((((type tty) (class color)) (:foreground "blue" :weight bold)) - (((class color) (background light)) (:foreground "Blue")) - (((class color) (background dark)) (:foreground "LightSkyBlue")) - (t (:inverse-video t :bold t))) + (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) (background light)) (:foreground "blue")) + (((class color) (min-colors 8) (background dark))))) "Face used for tables." :group 'org-faces) +(defface org-formula + (org-compatible-face + '((((class color) (min-colors 88) (background light)) (:foreground "Firebrick")) + (((class color) (min-colors 88) (background dark)) (:foreground "chocolate1")) + (((class color) (min-colors 8) (background light)) (:foreground "red")) + (((class color) (min-colors 8) (background dark)) (:foreground "red")) + (t (:bold t :italic t)))) + "Face for formulas." + :group 'org-faces) + +(defface org-scheduled-today + (org-compatible-face + '((((class color) (min-colors 88) (background light)) (:foreground "DarkGreen")) + (((class color) (min-colors 88) (background dark)) (:foreground "PaleGreen")) + (((class color) (min-colors 8)) (:foreground "green")) + (t (:bold t :italic t)))) + "Face for items scheduled for a certain day." + :group 'org-faces) + +(defface org-scheduled-previously + (org-compatible-face + '((((class color) (min-colors 88) (background light)) (:foreground "Firebrick")) + (((class color) (min-colors 88) (background dark)) (:foreground "chocolate1")) + (((class color) (min-colors 8) (background light)) (:foreground "red")) + (((class color) (min-colors 8) (background dark)) (:foreground "red" :bold t)) + (t (:bold t)))) + "Face for items scheduled previously, and not yet done." + :group 'org-faces) + (defface org-time-grid ;; font-lock-variable-name-face - '((((type tty) (class color)) (:foreground "yellow" :weight light)) - (((class color) (background light)) (:foreground "DarkGoldenrod")) - (((class color) (background dark)) (:foreground "LightGoldenrod")) - (t (:bold t :italic t))) + (org-compatible-face + '((((class color) (min-colors 16) (background light)) (:foreground "DarkGoldenrod")) + (((class color) (min-colors 16) (background dark)) (:foreground "LightGoldenrod")) + (((class color) (min-colors 8)) (:foreground "yellow" :weight light)))) ; FIXME: turn off??? "Face used for time grids." :group 'org-faces) -(defvar org-level-faces +(defconst org-level-faces '(org-level-1 org-level-2 org-level-3 org-level-4 org-level-5 org-level-6 org-level-7 org-level-8 )) -(defvar org-n-levels (length org-level-faces)) +(defconst org-n-levels (length org-level-faces)) +(defconst org-bold-re + (if (featurep 'xemacs) + "\\([ ]\\|^\\)\\(\\*\\(\\w[a-zA-Z0-9-_ ]*?\\w\\)\\*\\)\\([ ,.]\\|$\\)" + "\\([ ]\\|^\\)\\(\\*\\(\\w[[:word:] -_]*?\\w\\)\\*\\)\\([ ,.]\\|$\\)") + "Regular expression for bold emphasis.") +(defconst org-italic-re + (if (featurep 'xemacs) + "\\([ ]\\|^\\)\\(/\\(\\w[a-zA-Z0-9-_ ]*?\\w\\)/\\)\\([ ,.]\\|$\\)" + "\\([ ]\\|^\\)\\(/\\(\\w[[:word:] -_]*?\\w\\)/\\)\\([ ,.]\\|$\\)") + "Regular expression for italic emphasis.") +(defconst org-underline-re + (if (featurep 'xemacs) + "\\([ ]\\|^\\)\\(_\\(\\w[a-zA-Z0-9-_ ]*?\\w\\)_\\)\\([ ,.]\\|$\\)" + "\\([ ]\\|^\\)\\(_\\(\\w[[:word:] -_]*?\\w\\)_\\)\\([ ,.]\\|$\\)") + "Regular expression for underline emphasis.") ;; Variables for pre-computed regular expressions, all buffer local (defvar org-done-string nil @@ -2215,6 +2223,7 @@ Changing this variable requires a restart of Emacs to take effect." (setq int 'type kwds (append kwds (org-split-string value splitre)))) ((equal key "STARTUP") + (debug) (let ((opts (org-split-string value splitre)) (set '(("fold" org-startup-folded t) ("overview" org-startup-folded t) @@ -2324,7 +2333,10 @@ Changing this variable requires a restart of Emacs to take effect." (defvar orgtbl-mode) ; defined later in this file ;;; Define the mode -(defvar org-mode-map (copy-keymap outline-mode-map) +(defvar org-mode-map + (if (and (not (keymapp outline-mode-map)) (featurep 'allout)) + (error "Conflict with outdated version of allout.el. Load org.el before allout.el, or ugrade to newer allout, for example by switching to Emacs 22.") + (copy-keymap outline-mode-map)) "Keymap for Org-mode.") (defvar org-struct-menu) ; defined later in this file @@ -2728,9 +2740,12 @@ 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)) - (if em '("\\(\\W\\|^\\)\\(\\*\\w+\\*\\)\\(\\W\\|$\\)" 2 'bold prepend)) - (if em '("\\(\\W\\|^\\)\\(/\\w+/\\)\\(\\W\\|$\\)" 2 'italic prepend)) - (if em '("\\(\\W\\|^\\)\\(_\\w+_\\)\\(\\W\\|$\\)" 2 'underline prepend)) +; (if em '("\\(\\W\\|^\\)\\(\\*\\w+\\*\\)\\(\\W\\|$\\)" 2 'bold prepend)) +; (if em '("\\(\\W\\|^\\)\\(/\\w+/\\)\\(\\W\\|$\\)" 2 'italic prepend)) +; (if em '("\\(\\W\\|^\\)\\(_\\w+_\\)\\(\\W\\|$\\)" 2 'underline prepend)) + (if em (list org-bold-re 2 ''bold 'prepend)) + (if em (list org-italic-re 2 ''italic 'prepend)) + (if em (list org-underline-re 2 ''underline 'prepend)) (list (concat "^\\*+[ \t]*\\<\\(" org-comment-string "\\|" org-quote-string "\\)\\>") '(1 'org-special-keyword t)) @@ -3109,13 +3124,14 @@ or nil." (error (outline-next-heading))) (prog1 (match-string 0) (funcall outline-level))))) - (if (and (bolp) - (save-excursion (backward-char 1) (not (org-invisible-p)))) - (open-line 1) - (newline)) + (cond + ((and (org-on-heading-p) (bolp) + (save-excursion (backward-char 1) (not (org-invisible-p)))) + (open-line 1)) + ((bolp) nil) + (t (newline))) (insert head) - (if (looking-at "[ \t]*") - (replace-match " ")) + (just-one-space) (run-hooks 'org-insert-heading-hook)))) (defun org-insert-item () @@ -3128,8 +3144,20 @@ Return t when things worked, nil when we are not in an item." (org-at-item-p) t) (error nil))) - (unless (bolp) (newline)) - (insert (match-string 0)) + (let* ((bul (match-string 0)) + (eow (save-excursion (beginning-of-line 1) (looking-at "[ \t]*") + (match-end 0))) + (eowcol (save-excursion (goto-char eow) (current-column)))) + (cond + ((and (org-at-item-p) (<= (point) eow)) + ;; before the bullet + (beginning-of-line 1) + (open-line 1)) + ((<= (point) eow) + (beginning-of-line 1)) + (t (newline))) + (insert bul) + (just-one-space)) (org-maybe-renumber-ordered-list) t)) @@ -5335,7 +5363,8 @@ for a keyword. A numeric prefix directly selects the Nth keyword in (completion-ignore-case t) (org-select-this-todo-keyword (if (stringp arg) arg - (and arg (integerp arg) (nth (1- arg) org-todo-keywords)))) + (and arg (integerp arg) (> arg 0) + (nth (1- arg) org-todo-keywords)))) rtn rtnall files file pos) (when (equal arg '(4)) (setq org-select-this-todo-keyword @@ -5935,6 +5964,7 @@ the documentation of `org-diary'." "Return the TODO information for agenda display." (let* ((props (list 'face nil 'done-face 'org-done + 'org-not-done-regexp org-not-done-regexp 'mouse-face 'highlight 'keymap org-agenda-keymap 'help-echo @@ -5975,6 +6005,7 @@ the documentation of `org-diary'." (defun org-agenda-get-timestamps () "Return the date stamp information for agenda display." (let* ((props (list 'face nil + 'org-not-done-regexp org-not-done-regexp 'mouse-face 'highlight 'keymap org-agenda-keymap 'help-echo @@ -6040,6 +6071,7 @@ the documentation of `org-diary'." (defun org-agenda-get-closed () "Return the logged TODO entries for agenda display." (let* ((props (list 'mouse-face 'highlight + 'org-not-done-regexp org-not-done-regexp 'keymap org-agenda-keymap 'help-echo (format "mouse-2 or RET jump to org file %s" @@ -6091,6 +6123,7 @@ the documentation of `org-diary'." "Return the deadline information for agenda display." (let* ((wdays org-deadline-warning-days) (props (list 'mouse-face 'highlight + 'org-not-done-regexp org-not-done-regexp 'keymap org-agenda-keymap 'help-echo (format "mouse-2 or RET jump to org file %s" @@ -6146,6 +6179,7 @@ the documentation of `org-diary'." (defun org-agenda-get-scheduled () "Return the scheduled information for agenda display." (let* ((props (list 'face 'org-scheduled-previously + 'org-not-done-regexp org-not-done-regexp 'undone-face 'org-scheduled-previously 'done-face 'org-done 'mouse-face 'highlight @@ -6195,6 +6229,7 @@ the documentation of `org-diary'." (defun org-agenda-get-blocks () "Return the date-range information for agenda display." (let* ((props (list 'face nil + 'org-not-done-regexp org-not-done-regexp 'mouse-face 'highlight 'keymap org-agenda-keymap 'help-echo @@ -6430,8 +6465,25 @@ HH:MM." (defun org-finalize-agenda-entries (list) "Sort and concatenate the agenda items." + (setq list (mapcar 'org-agenda-highlight-todo list)) (mapconcat 'identity (sort list 'org-entries-lessp) "\n")) +(defun org-agenda-highlight-todo (x) + (let (re) + (if (eq x 'line) + (save-excursion + (beginning-of-line 1) + (setq re (get-text-property (point) 'org-not-done-regexp)) + (goto-char (+ (point) (get-text-property (point) 'prefix-length))) + (and (looking-at (concat "[ \t]*" re)) + (add-text-properties (match-beginning 0) (match-end 0) + '(face org-todo)))) + (setq re (get-text-property 0 'org-not-done-regexp x)) + (and re (string-match re x) + (add-text-properties (match-beginning 0) (match-end 0) + '(face org-todo) x)) + x))) + (defsubst org-cmp-priority (a b) "Compare the priorities of string A and B." (let ((pa (or (get-text-property 1 'priority a) 0)) @@ -6582,7 +6634,7 @@ the same tree node, and the headline of the tree node in the Org-mode file." (and (outline-next-heading) (org-flag-heading nil))) ; show the next heading (org-todo arg) - (forward-char 1) + (and (bolp) (forward-char 1)) (setq newhead (org-get-heading)) (save-excursion (org-back-to-heading) @@ -6622,12 +6674,13 @@ the new TODO state." (replace-match new t t) (beginning-of-line 1) (add-text-properties (point-at-bol) (point-at-eol) props) - (if fixface - (add-text-properties - (point-at-bol) (point-at-eol) - (list 'face - (if org-last-todo-state-is-todo - undone-face done-face)))) + (when fixface + (add-text-properties + (point-at-bol) (point-at-eol) + (list 'face + (if org-last-todo-state-is-todo + undone-face done-face))) + (org-agenda-highlight-todo 'line)) (beginning-of-line 1)) (error "Line update did not work"))) (beginning-of-line 0))))) @@ -7348,9 +7401,8 @@ optional argument IN-EMACS is non-nil, Emacs will visit the file." (org-add-props cmd nil 'face 'org-warning)))) (progn - (message "Executing %s..." cmd) - (shell-command cmd) - (message "Executing %s...done" cmd)) + (message "Executing %s" cmd) + (shell-command cmd)) (error "Abort")))) (t @@ -7804,7 +7856,10 @@ If the file does not exist, an error is thrown." (setq cmd 'emacs)))) (cond ((and (stringp cmd) (not (string-match "^\\s-*$" cmd))) - (setq cmd (format cmd (concat "\"" file "\""))) + ;; Normalize use of quote, this can vary. + (if (string-match "['\"]%s['\"]" cmd) + (setq cmd (replace-match "'%s'" t t cmd))) + (setq cmd (format cmd file)) (save-window-excursion (shell-command (concat cmd " &")))) ((or (stringp cmd) @@ -8198,12 +8253,16 @@ is in the current directory or below." (complete-file ;; Completing read for file names. (setq file (read-file-name "File: ")) - (let ((pwd (file-name-as-directory (expand-file-name ".")))) + (let ((pwd (file-name-as-directory (expand-file-name "."))) + (pwd1 (file-name-as-directory (abbreviate-file-name + (expand-file-name "."))))) (cond ((equal complete-file '(16)) (setq link (org-make-link "file:" (abbreviate-file-name (expand-file-name file))))) + ((string-match (concat "^" (regexp-quote pwd1) "\\(.+\\)") file) + (setq link (org-make-link "file:" (match-string 1 file)))) ((string-match (concat "^" (regexp-quote pwd) "\\(.+\\)") (expand-file-name file)) (setq link (org-make-link @@ -8850,10 +8909,10 @@ Optional argument NEW may specify text to replace the current field content." e (not (= (match-beginning 2) (match-end 2)))) (setq f (format (if num " %%%ds %s" " %%-%ds %s") l (if e "|" (setq org-table-may-need-update t) "")) - n (format f s t t)) + n (format f s)) (if new - (if (<= (length new) l) - (setq n (format f new t t)) ;; FIXME: why t t????? + (if (<= (length new) l) ;; FIXME: length -> str-width? + (setq n (format f new t t)) ;; FIXME: t t? (setq n (concat new "|") org-table-may-need-update t))) (or (equal n o) (let (org-table-may-need-update) @@ -11796,14 +11855,27 @@ headlines. The default is 3. Lower levels will become bulleted lists." ;; FILE link (let* ((filename path) (abs-p (file-name-absolute-p filename)) - (thefile (if abs-p (expand-file-name filename) filename)) - (thefile (save-match-data - (if (string-match ":[0-9]+$" thefile) - (replace-match "" t t thefile) - thefile))) - (file-is-image-p - (save-match-data - (string-match (org-image-file-name-regexp) thefile)))) + thefile file-is-image-p search) + (save-match-data + (if (string-match "::\\(.*\\)" filename) + (setq search (match-string 1 filename) + filename (replace-match "" nil nil filename))) + (setq file-is-image-p + (string-match (org-image-file-name-regexp) filename)) + (setq thefile (if abs-p (expand-file-name filename) filename)) + (when (and org-export-html-link-org-files-as-html + (string-match "\\.org$" thefile)) + (setq thefile (concat (substring thefile 0 + (match-beginning 0)) + ".html")) + (if (and search + ;; make sure this is can be used as target search + (not (string-match "^[0-9]*$" search)) + (not (string-match "^\\*" search)) + (not (string-match "^/.*/$" search))) + (setq thefile (concat thefile "#" + (org-solidify-link-text + (org-link-unescape search))))))) (setq rpl (if (and org-export-html-inline-images file-is-image-p) (concat "") @@ -12157,14 +12229,13 @@ stacked delimiters is N. Escaping delimiters is not possible." string) (defun org-export-html-convert-emphasize (string) - (let (c (s 0)) - (while (string-match "\\(\\W\\|^\\)\\([*/_]\\)\\(\\w+\\)\\2\\(\\W\\|$\\)" string s) - (setq c (cdr (assoc (match-string 2 string) - '(("*" . "b") ("/" . "i") ("_" . "u")))) - s (+ (match-end 0) 3) - string (replace-match - (concat "\\1<" c ">\\3\\4") t nil string))) - string)) + (while (string-match org-italic-re string) + (setq string (replace-match "\\1\\3\\4" t nil string))) + (while (string-match org-bold-re string) + (setq string (replace-match "\\1\\3\\4" t nil string))) + (while (string-match org-underline-re string) + (setq string (replace-match "\\1\\3\\4" t nil string))) + string) (defun org-parse-key-lines () "Find the special key lines with the information for exporters." @@ -12589,6 +12660,8 @@ a time), or the day by one (if it does not contain a time)." (define-key org-mode-map [?\C-c ?\C-x (right)] 'org-shiftright) ;; All the other keys + +(define-key org-mode-map "\C-c\C-a" 'show-all) ; in case allout messed up. (define-key org-mode-map "\C-c$" 'org-archive-subtree) (define-key org-mode-map "\C-c\C-j" 'org-goto) (define-key org-mode-map "\C-c\C-t" 'org-todo) diff --git a/org.pdf b/org.pdf index 45cde549b..0f25dfd2c 100644 Binary files a/org.pdf and b/org.pdf differ diff --git a/org.texi b/org.texi index 5108dffae..81e57f137 100644 --- a/org.texi +++ b/org.texi @@ -4,7 +4,7 @@ @c @setfilename ../info/org @settitle Org Mode Manual -@set VERSION 4.24 +@set VERSION 4.26 @set DATE April 2006 @dircategory Emacs @@ -76,13 +76,13 @@ Software Foundation raise funds for GNU development.'' @menu * Introduction:: Getting started -* Document Structure:: A tree works like your brain +* Document structure:: A tree works like your brain * Tables:: Pure magic for quick formatting * Hyperlinks:: Notes in context * TODO items:: Every tree branch can be a TODO item * Timestamps:: Assign date and time to items * Tags:: Tagging headlines and matching sets of tags -* Agenda Views:: Collecting information into views +* Agenda views:: Collecting information into views * Exporting:: Sharing and publishing of notes * Miscellaneous:: All the rest which did not fit elsewhere * Index:: The fast road to specific information @@ -97,7 +97,7 @@ Introduction * Installation and activation:: How to install Org-mode * Feedback:: Bug reports, ideas, patches etc. -Document Structure +Document structure * Outlines:: Org-mode is based on outline-mode * Headlines:: How to typeset org-tree headlines @@ -106,7 +106,7 @@ Document Structure * Structure editing:: Changing sequence and level of headlines * Archiving:: Move done task trees to a different place * Sparse trees:: Matches embedded in context -* Plain Lists:: Editing hand-formatted lists +* Plain lists:: Editing hand-formatted lists Tables @@ -130,7 +130,7 @@ Hyperlinks * Link format:: How links in Org-mode are formatted * Internal links:: Links to other places in the current file * External links:: URL-like links to the world -* Managing links:: Creating, inserting and following +* Handling links:: Creating, inserting and following * Search Options:: Linking to a specific location * Remember:: Org-trees store quick notes @@ -163,11 +163,11 @@ Tags * Setting tags:: How to assign tags to a headline * Tag searches:: Searching for combinations of tags -Agenda Views +Agenda views * Agenda files:: Files being searched for agenda information * Agenda dispatcher:: Keyboard access to agenda views -* Weekly/Daily Agenda:: The calendar page with current tasks +* 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 * Timeline:: Time-sorted view for single file @@ -210,7 +210,7 @@ Miscellaneous @end detailmenu @end menu -@node Introduction, Document Structure, Top, Top +@node Introduction, Document structure, Top, Top @chapter Introduction @cindex introduction @@ -242,10 +242,10 @@ structured ASCII file, as HTML, or (todo and agenda items only) as an iCalendar file. Org-mode keeps simple things simple. When first fired up, it should -feel like a simple but easy to use outliner. Complexity is not -imposed, but a large amount of functionality is available when you -need it. Org-mode can be used on different levels and in different -ways, for example: +feel like a simple, easy to use outliner. Complexity is not imposed, +but a large amount of functionality is available when you need it. +Org-mode can be used on different levels and in different ways, for +example: @example @r{@bullet{} as an outline extension with visibility cycling and structure editing} @@ -339,7 +339,7 @@ with clear information about: @end enumerate @noindent Thank you for helping to improve this mode. -@node Document Structure, Tables, Introduction, Top +@node Document structure, Tables, Introduction, Top @chapter Document Structure @cindex document structure @cindex structure of document @@ -355,10 +355,10 @@ edit the structure of the document. * Structure editing:: Changing sequence and level of headlines * Archiving:: Move done task trees to a different place * Sparse trees:: Matches embedded in context -* Plain Lists:: Editing hand-formatted lists +* Plain lists:: Editing hand-formatted lists @end menu -@node Outlines, Headlines, Document Structure, Document Structure +@node Outlines, Headlines, Document structure, Document structure @section Outlines @cindex outlines @cindex outline-mode @@ -373,7 +373,7 @@ outlines by compressing the entire show/hide functionality into a single command @command{org-cycle}, which is bound to the @key{TAB} key. -@node Headlines, Visibility cycling, Outlines, Document Structure +@node Headlines, Visibility cycling, Outlines, Document structure @section Headlines @cindex headlines @cindex outline tree @@ -396,7 +396,7 @@ example: outline that has whitespace followed by a single star as headline starters. @ref{Clean view} describes a setup to realize this. -@node Visibility cycling, Motion, Headlines, Document Structure +@node Visibility cycling, Motion, Headlines, Document structure @section Visibility cycling @cindex cycling, visibility @cindex visibility cycling @@ -458,7 +458,7 @@ buffer: #+STARTUP: showall @end example -@node Motion, Structure editing, Visibility cycling, Document Structure +@node Motion, Structure editing, Visibility cycling, Document structure @section Motion @cindex motion, between headlines @cindex jumping, to headlines @@ -491,7 +491,7 @@ the original buffer, and the headings hierarchy above it is made visible. @end table -@node Structure editing, Archiving, Motion, Document Structure +@node Structure editing, Archiving, Motion, Document structure @section Structure editing @cindex structure editing @cindex headline, promotion and demotion @@ -507,9 +507,14 @@ visible. @kindex M-@key{RET} @item M-@key{RET} Insert new heading with same level as current. If the cursor is in a -plain list item, a new item is created. To force creation of a new -headline, use a prefix arg, or first press @key{RET} to get to the -beginning of the next line. +plain list item, a new item is created (@pxref{Plain lists}). To force +creation of a new headline, use a prefix arg, or first press @key{RET} +to get to the beginning of the next line. When this command is used in +the middle of a line, the line is split and the rest of the line becomes +the new headline. If the command is used at the beginning of a +headline, the new headline is created before the current line. It at +the beginning of any other line, the content of that line is made the +new heading. @kindex M-S-@key{RET} @item M-S-@key{RET} Insert new TODO entry with same level as current heading. @@ -559,7 +564,7 @@ just after the last headline to change. Note that when the cursor is inside a table (@pxref{Tables}), the Meta-Cursor keys have different functionality. -@node Archiving, Sparse trees, Structure editing, Document Structure +@node Archiving, Sparse trees, Structure editing, Document structure @section Archiving @cindex archiving @cindex filing subtrees @@ -583,7 +588,7 @@ this, see the documentation string of the variable agenda, archiving to a different file is a good way to keep archived trees from contributing agenda items. -@node Sparse trees, Plain Lists, Archiving, Document Structure +@node Sparse trees, Plain lists, Archiving, Document structure @section Sparse trees @cindex sparse trees @cindex trees, sparse @@ -637,14 +642,14 @@ C-v} creates a sparse TODO tree (@pxref{TODO basics}). To print a sparse tree, you can use the Emacs command @code{ps-print-buffer-with-faces} which does not print invisible parts of the document @footnote{This does not work under XEmacs, because -XEmacs uses selective display for outlining, not text properties}. +XEmacs uses selective display for outlining, not text properties.}. Or you can use the command @kbd{C-c C-x v} to copy the visible part of the document to another file (extension @file{.txt}) which can then be printed in any desired way. -@node Plain Lists, , Sparse trees, Document Structure -@section Plain Lists +@node Plain lists, , Sparse trees, Document structure +@section Plain lists @cindex plain lists @cindex lists, plain @cindex lists, ordered @@ -673,6 +678,7 @@ ends before the next line that is indented like the bullet/number, or less. For example: @example +@group ** Lord of the Rings My favorite scenes are (in this order) 1. Eowyns fight with the witch king @@ -682,6 +688,8 @@ My favorite scenes are (in this order) 3. Peter Jackson being shot by Legolas - on DVD only He makes a really funny face when it happens. +But in the end, not individual scenes matter but the film as a whole. +@end group @end example Org-mode supports these lists by tuning filling and wrapping commands @@ -699,7 +707,14 @@ always subordinate to real headlines, the hierarchies remain completely separated. @kindex M-@key{RET} @item M-@key{RET} -Insert new item at current level. With prefix arg, for a new heading. +Insert new item at current level. With prefix arg, force a new heading +(@pxref{Structure editing}). If this command is used in the middle of a +line, the line is @emph{split} and the rest of the line becomes the new +item. If this command is executed in the @emph{whitespace before a bullet or +number}, the new item is created @emph{before} the current item. If the +command is executed in the white space before the text that is part of +an item but does not contain the bullet, a bullet is added to the +current line. @kindex M-S-@key{up} @kindex M-S-@key{down} @item M-S-@key{up} @@ -722,7 +737,7 @@ the command chain with a cursor motion or so. Renumber the ordered list at the cursor. @end table -@node Tables, Hyperlinks, Document Structure, Top +@node Tables, Hyperlinks, Document structure, Top @chapter Tables @cindex tables @cindex editing tables @@ -986,9 +1001,10 @@ The width of columns is automatically determined by the table editor. Sometimes a single field or a few fields need to carry more text, leading to inconveniently wide columns. To limit@footnote{This feature does not work on XEmacs.} the width of a column, one field anywhere in -the column must carry the string @samp{} where @samp{N} is an integer -specifying the width of the column in characters. The next re-align -will then set the width of this column to no more than this value. +the column may contain just the string @samp{} where @samp{N} is an +integer specifying the width of the column in characters. The next +re-align will then set the width of this column to no more than this +value. @example |---+------------------------------| |---+--------| @@ -1360,7 +1376,7 @@ links to other files, Usenet articles, emails and much more. * Link format:: How links in Org-mode are formatted * Internal links:: Links to other places in the current file * External links:: URL-like links to the world -* Managing links:: Creating, inserting and following +* Handling links:: Creating, inserting and following * Search Options:: Linking to a specific location * Remember:: Org-trees store quick notes @end menu @@ -1401,26 +1417,28 @@ internal structure of all links, use the menu entry @cindex links, internal @cindex CamelCase links -If the link text does not look like a URL, links are considered to be -internal in the current file. Links such as @samp{[[My Target]]} or -@samp{[[My Target][Find my target]]} lead to a text search in the -current file. The link can be followed with @kbd{C-c C-o} when the -cursor is on the link, or with a mouse click (@pxref{Managing links}). -The preferred match for such a link is a dedicated target: The same -string in double angular brackets. Targets may be located anywhere, -often it is convenient to put them into a comment line, for example +If the link does not look like a URL, it is considered to be internal in +the current file. Links such as @samp{[[My Target]]} or @samp{[[My +Target][Find my target]]} lead to a text search in the current file. +The link can be followed with @kbd{C-c C-o} when the cursor is on the +link, or with a mouse click (@pxref{Handling links}). The preferred +match for such a link is a dedicated target: The same string in double +angular brackets. Targets may be located anywhere, often it is +convenient to put them into a comment line, for example @example # <> @end example +@noindent In HTML export (@pxref{HTML export}), such targets will become +named anchors for direct access through @samp{http} links. + If no dedicated target exists, Org-mode will search for the words in the -link, often removing the need for a dedicated target. In the above -example the search would be for @samp{my target}. Links starting with a -star like @samp{*My Target} restrict the search to headlines. When -searching, Org-mode will first try an exact match, but then move on to -more and more lenient searches. For example, the link @samp{[[*My -Targets]]} will find any of the following: +link. In the above example the search would be for @samp{my target}. +Links starting with a star like @samp{*My Target} restrict the search to +headlines. When searching, Org-mode will first try an exact match, but +then move on to more and more lenient searches. For example, the link +@samp{[[*My Targets]]} will find any of the following: @example ** My targets @@ -1431,7 +1449,7 @@ Targets]]} will find any of the following: To insert a link targeting a headline, in-buffer completion can be used. Just type a star followed by a few optional letters into the buffer and press @kbd{M-@key{TAB}}. All headlines in the current buffer will be -offered as completions. @xref{Managing links}, for more commands +offered as completions. @xref{Handling links}, for more commands creating links. Following a link pushes a mark onto Org-mode's own mark ring. You can @@ -1469,7 +1487,7 @@ the option @code{org-activate-links}. A CamelCase word then leads to a text search such that @samp{CamelCaseLink} is equivalent to @samp{[[camel case link]]}. -@node External links, Managing links, Internal links, Hyperlinks +@node External links, Handling links, Internal links, Hyperlinks @section External links @cindex links, external @cindex external links @@ -1525,8 +1543,8 @@ as links. If spaces must be part of the link (for example in @samp{bbdb:Richard Stallman}) or to remove ambiguities about the end of the link, enclose them in angular brackets. -@node Managing links, Search Options, External links, Hyperlinks -@section Managing links +@node Handling links, Search Options, External links, Hyperlinks +@section Handling links Org-mode provides methods to create a link in the correct syntax, to insert it into an org-mode file, and to follow the link. @@ -1537,15 +1555,17 @@ insert it into an org-mode file, and to follow the link. @item C-c l Store a link to the current location. This is a @emph{global} command which can be used in any buffer to create a link. The link will be -stored for later insertion into an Org-mode buffer (see below). For VM, -RMAIL, WANDERLUST, MH-E, GNUS and BBDB buffers, the link will point to -the current article/entry. For W3 and W3M buffers, the link goes to the -current URL. For Org-mode files, the current headline is targeted. For -any other files, the link will point to the file, with a search string -(@pxref{Search Options}) pointing to the contents of the current line. -If there is an active region, the selected words will form the basis of -the search string. The key binding @kbd{C-c l} is only a suggestion - -see @ref{Installation and activation}. +stored for later insertion into an Org-mode buffer (see below). For +Org-mode files, if there is a @samp{<>} at the cursor, the link +points to the target. Otherwise it points to the current headline. For +VM, RMAIL, WANDERLUST, MH-E, GNUS and BBDB buffers, the link will +indicate to the current article/entry. For W3 and W3M buffers, the link +goes to the current URL. For any other files, the link will point to +the file, with a search string (@pxref{Search Options}) pointing to the +contents of the current line. If there is an active region, the +selected words will form the basis of the search string. The key +binding @kbd{C-c l} is only a suggestion - see @ref{Installation and +activation}. @kindex C-c C-l @cindex link completion @@ -1556,12 +1576,12 @@ Insert a link. This prompts for a link to be inserted into the buffer. You can just type a link, using text for an internal link, or one of the link type prefixes mentioned in the examples above. Through completion, all links stored during the current session can be accessed. The link -will be formatted as given in the variable @code{org-link-format} and -inserted into the buffer, along with a descriptive text. Note that you -don't have to use this command to insert a link. Links in Org-mode are -plain text, and you can type or paste them straight into the buffer. -By using this command, the links are automatically enclosed in double -brackets, and you will be asked for the optional descriptive text. +will be inserted into the buffer, along with a descriptive text. Note +that you don't have to use this command to insert a link. Links in +Org-mode are plain text, and you can type or paste them straight into +the buffer. By using this command, the links are automatically enclosed +in double brackets, and you will be asked for the optional descriptive +text. @kindex C-u C-c C-l @cindex file name completion @@ -1571,9 +1591,10 @@ When @kbd{C-c C-l} is called with a @kbd{C-u} prefix argument, a link to a file will be inserted and you may use file name completion to select the name of the file. The path to the file is inserted relative to the directory of the current org file, if the linked file is in the current -directory or in a subdirectory of it. Otherwise an absolute path, if -possible with @samp{~/} for your home directory is used. You can force -an absolute path with two @kbd{C-u} prefixes. +directory or in a subdirectory of it, or if the path is written relative +to the current directory using @samp{../}. Otherwise an absolute path +is used, if possible with @samp{~/} for your home directory. You can +force an absolute path with two @kbd{C-u} prefixes. @item C-c C-l @r{with cursor on existing link} When the cursor is on an existing link, @kbd{C-c C-l} allows to edit the @@ -1622,7 +1643,7 @@ previously recorded positions. @end table -@node Search Options, Remember, Managing links, Hyperlinks +@node Search Options, Remember, Handling links, Hyperlinks @section Search options in file links @cindex search option in file links @cindex file links, searching @@ -1648,7 +1669,9 @@ Jump to line 255. @item My Target Search for a link target @samp{<>}, or do a text search for @samp{my target}, similar to the search in internal links, see -@ref{Internal links}. +@ref{Internal links}. In HTML export (@pxref{HTML export}), such a file +link will become an html reference to the corresponding named anchor in +the linked file. @item *My Target In an Org-mode file, restrict search to headlines. @item /regexp/ @@ -1821,13 +1844,13 @@ numerical prefix N, show the tree for the Nth keyword in the variable @kindex C-c a t @item C-c a t Show the global TODO list. This collects the TODO items from all -agenda files (@pxref{Agenda Views}) into a single buffer. The buffer is in +agenda files (@pxref{Agenda views}) into a single buffer. The buffer is in @code{agenda-mode}, so there are commands to examine and manipulate the TODO entries directly from that buffer (@pxref{Agenda commands}). @xref{Global TODO list}, for more information. -@item @code{org-agenda-include-all-todo} -If you would like to have all your TODO items listed as part of your -agenda, customize the variable @code{org-agenda-include-all-todo}. +@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}. @end table @node Progress logging, TODO extensions, TODO basics, TODO items @@ -1847,7 +1870,7 @@ C-t} in the Org-mode buffer or @kbd{t} in the agenda buffer, a line @samp{CLOSED: [timestamp]} will be inserted just after the headline. If you turn the entry back into a TODO item again through further state cycling, that line will be removed again. In the timeline -(@pxref{Timeline}) and in the agenda (@pxref{Weekly/Daily Agenda}), +(@pxref{Timeline}) and in the agenda (@pxref{Weekly/Daily agenda}), you can then use the @kbd{L} key to display the TODO items closed on each day, giving you an overview of what has been done on a day. @@ -1989,7 +2012,7 @@ headline, like this With its standard setup, Org-mode supports priorities @samp{A}, @samp{B}, and @samp{C}. @samp{A} is the highest priority. An entry without a cookie is treated as priority @samp{B}. Priorities make a -difference only in the agenda (@pxref{Weekly/Daily Agenda}). +difference only in the agenda (@pxref{Weekly/Daily agenda}). @table @kbd @kindex @kbd{C-c ,} @@ -2034,14 +2057,16 @@ A time stamp is a specification of a date (possibly with time) in a special format, either @samp{<2003-09-16 Tue>} or @samp{<2003-09-16 Tue 09:39>}. A time stamp can appear anywhere in the headline or body of an org-tree entry. Its presence allows entries to be shown on specific -dates in the agenda (@pxref{Weekly/Daily Agenda}). We distinguish: +dates in the agenda (@pxref{Weekly/Daily agenda}). We distinguish: @table @var @cindex timestamp @item TIMESTAMP -A simple time stamp just assigns a date/time to an item. In the -timeline and agenda displays, the headline of the entry will be shown -exactly on that date. +A simple time stamp just assigns a date/time to an item. This is just +like writing down an appointment in a paper agenda, or like writing down +an event in a diary, when you want to take not of when something +happened. In the timeline and agenda displays, the headline of an entry +associated with a plain time stamp will be shown exactly on that date. @item TIMERANGE @cindex timerange @@ -2055,6 +2080,21 @@ example: <2004-08-23 Mon>--<2004-08-26 Thu> @end example +@item SCHEDULED +@cindex SCHEDULED keyword +If a time stamp is preceded by the word @samp{SCHEDULED:}, it means you +are planning to start working on that task on the given date. So this is +not about recording an event, but about planning your work. The +headline will be listed under the given date. In addition, a reminder +that the scheduled date has passed will be present in the compilation +for @emph{today}, until the entry is marked DONE. I.e., the task will +automatically be forwarded until completed. + +@example +*** TODO Call Trillian for a date on New Years Eve. + SCHEDULED: <2004-12-25 Sat> +@end example + @item DEADLINE @cindex DEADLINE keyword If a time stamp is preceded by the word @samp{DEADLINE:}, the task @@ -2069,15 +2109,6 @@ continuing until the entry is marked DONE. An example: The editor in charge is DEADLINE: <2004-02-29 Sun> @end example - -@item SCHEDULED -@cindex SCHEDULED keyword -If a time stamp is preceded by the word @samp{SCHEDULED:}, it means -you are planning to start working on that task on the given date. The -headline will be listed under the given date. In addition, a reminder -that the scheduled date has passed will be present in the compilation -for @emph{today}, until the entry is marked DONE. I.e., the -task will automatically be forwarded. @end table @node Creating timestamps, , Time stamps, Timestamps @@ -2120,7 +2151,7 @@ instead. @kindex C-c C-o @item C-c C-o Access the agenda for the date given by the time stamp at point -(@pxref{Weekly/Daily Agenda}). +(@pxref{Weekly/Daily agenda}). @kindex C-c C-d @item C-c C-d @@ -2207,7 +2238,7 @@ One month back. Choose date in calendar (only if nothing typed into minibuffer). @end table -@node Tags, Agenda Views, Timestamps, Top +@node Tags, Agenda views, Timestamps, Top @chapter Tags @cindex tags @cindex headline tagging @@ -2311,7 +2342,7 @@ tagged @samp{:WORK:} or @samp{:LAPTOP:}. The string @samp{WORK|LAPTOP&NIGHT} requires that the @samp{:LAPTOP:} lines are also tagged @samp{NIGHT}. -@node Agenda Views, Exporting, Tags, Top +@node Agenda views, Exporting, Tags, Top @chapter Agenda Views @cindex agenda views @@ -2345,14 +2376,14 @@ edit these files remotely. @menu * Agenda files:: Files being searched for agenda information * Agenda dispatcher:: Keyboard access to agenda views -* Weekly/Daily Agenda:: The calendar page with current tasks +* 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 * Timeline:: Time-sorted view for single file * Agenda commands:: Remote editing of org trees @end menu -@node Agenda files, Agenda dispatcher, Agenda Views, Agenda Views +@node Agenda files, Agenda dispatcher, Agenda views, Agenda views @section Agenda files The information to be shown is collected from all @emph{agenda files}, @@ -2385,7 +2416,7 @@ Cycle through agenda file list, visiting one file after the other. The Org menu contains the current list of files and can be used to visit any of them. -@node Agenda dispatcher, Weekly/Daily Agenda, Agenda files, Agenda Views +@node Agenda dispatcher, Weekly/Daily agenda, Agenda files, Agenda views @section The agenda dispatcher @cindex agenda dispatcher @cindex dispatching agenda commands @@ -2400,7 +2431,7 @@ letter is required to execute a command. The dispatcher offers the following default commands: @table @kbd @item a -Create the calendar-like agenda (@pxref{Weekly/Daily Agenda}). +Create the calendar-like agenda (@pxref{Weekly/Daily agenda}). @item t / T Create a list of all TODO items (@pxref{Global TODO list}). @item m / M @@ -2438,7 +2469,7 @@ f} to create a sparse tree with all entries containing the word @samp{FIXME}. For more information, look at the documentation string of the variable @code{org-agenda-custom-commands}. -@node Weekly/Daily Agenda, Global TODO list, Agenda dispatcher, Agenda Views +@node Weekly/Daily agenda, Global TODO list, Agenda dispatcher, Agenda views @section The weekly/daily agenda @cindex agenda @@ -2468,7 +2499,7 @@ commands}. * Sorting of agenda items:: The order of things @end menu -@node Categories, Time-of-day specifications, Weekly/Daily Agenda, Weekly/Daily Agenda +@node Categories, Time-of-day specifications, Weekly/Daily agenda, Weekly/Daily agenda @subsection Categories @cindex category @@ -2485,7 +2516,7 @@ for the text below it (but the first category also applies to any text before the first CATEGORY line). The display in the agenda buffer looks best if the category is not longer than 10 characters. -@node Time-of-day specifications, Calendar/Diary integration, Categories, Weekly/Daily Agenda +@node Time-of-day specifications, Calendar/Diary integration, Categories, Weekly/Daily agenda @subsection Time-of-Day Specifications Org-mode checks each agenda item for a time-of-day specification. The @@ -2533,7 +2564,7 @@ The time grid can be turned on and off with the variable @code{org-agenda-time-grid}. -@node Calendar/Diary integration, Sorting of agenda items, Time-of-day specifications, Weekly/Daily Agenda +@node Calendar/Diary integration, Sorting of agenda items, Time-of-day specifications, Weekly/Daily agenda @subsection Calendar/Diary integration @cindex calendar integration @cindex diary integration @@ -2564,7 +2595,7 @@ Sunrise/Sunset times, show lunar phases and to convert to other calendars, respectively. @kbd{c} can be used to switch back and forth between calendar and agenda. -@node Sorting of agenda items, , Calendar/Diary integration, Weekly/Daily Agenda +@node Sorting of agenda items, , Calendar/Diary integration, Weekly/Daily agenda @subsection Sorting of agenda items @cindex sorting, of agenda items @cindex priorities, of agenda items @@ -2583,7 +2614,7 @@ Sorting can be customized using the variable @code{org-agenda-sorting-strategy}. -@node Global TODO list, Matching headline tags, Weekly/Daily Agenda, Agenda Views +@node Global TODO list, Matching headline tags, Weekly/Daily agenda, Agenda views @section The global TODO list @cindex global TODO list @cindex TODO list, global @@ -2595,7 +2626,7 @@ collected into a single place. @kindex C-c a t @item C-c a t Show the global TODO list. This collects the TODO items from all -agenda files (@pxref{Agenda Views}) into a single buffer. The buffer is in +agenda files (@pxref{Agenda views}) into a single buffer. The buffer is in @code{agenda-mode}, so there are commands to examine and manipulate the TODO entries directly from that buffer (@pxref{Agenda commands}). @xref{Global TODO list}, for more information. @@ -2616,7 +2647,7 @@ Remote editing of TODO items means that you can change the state of a TODO entry with a single key press. The commands available in the TODO list are described in @ref{Agenda commands}. -@node Matching headline tags, Timeline, Global TODO list, Agenda Views +@node Matching headline tags, Timeline, Global TODO list, Agenda views @section Matching headline tags @cindex matching, of tags @cindex tags view @@ -2643,7 +2674,7 @@ and force checking subitems (see variable The commands available in the tags list are described in @ref{Agenda commands}. -@node Timeline, Agenda commands, Matching headline tags, Agenda Views +@node Timeline, Agenda commands, Matching headline tags, Agenda views @section Timeline for a single file @cindex single file summary @cindex agenda, for single file @@ -2669,7 +2700,7 @@ When called with a @kbd{C-u} prefix, all unfinished TODO entries The commands available in the timeline buffer are listed in @ref{Agenda commands}. -@node Agenda commands, , Timeline, Agenda Views +@node Agenda commands, , Timeline, Agenda views @section Commands in the agenda buffer @cindex commands, in agenda buffer @@ -2886,7 +2917,7 @@ visit org files will not be removed. @end table -@node Exporting, Miscellaneous, Agenda Views, Top +@node Exporting, Miscellaneous, Agenda views, Top @chapter Exporting @cindex exporting @@ -3003,6 +3034,9 @@ the new style visible to Emacs. This command restarts org-mode for the current buffer and forces Emacs to re-evaluate the local variables section in the buffer. +@c FIXME: More about header and footer styles +@c FIXME: Talk about links and targets. + @node XML export, iCalendar export, HTML export, Exporting @section XML export @cindex XML export @@ -3114,7 +3148,7 @@ formatted output. @item Plain lists @samp{-}, @samp{*} or @samp{+} as bullet, or with @samp{1.} or @samp{2)} as enumerator will be recognized and transformed if the -backend supports lists. See @xref{Plain Lists}. +backend supports lists. See @xref{Plain lists}. @cindex underlined text @cindex bold text @@ -3323,7 +3357,7 @@ variable is @code{org-startup-align-all-tables}, with a default value @code{nil}. @example align @r{align all tables} -noalign @r{don't align table on startup} +noalign @r{don't align tables on startup} @end example Here are the options for hiding leading stars in outline headings. The corresponding variables are @code{org-hide-leading-stars} and @@ -3346,7 +3380,7 @@ end of the file. @item #+TBLFM: This line contains the formulas for the table directly above the line. @item #+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+TEXT:, #+OPTIONS: -These line provide setting for exporting files. For more details see +These lines provide setting for exporting files. For more details see @ref{Export options}. @end table @@ -3534,10 +3568,24 @@ rather use @kbd{C-c .} to re-insert the timestamp. @cindex FAQ @enumerate + +@cindex allout.el, conflict with +@cindex @code{keymapp nil} error +@item @b{When I try to use Org-mode, I always get +@code{(wrong-type-argument keymapp nil)}}.@* +This is a conflict with an outdated version of the @file{allout.el} +package which pretends to be also the standard outline-mode but is not. +This happens with older versions of @file{allout.el}, for example the +one distributed with Emacs 21. Upgrade to Emacs 22 and this problem +will disappear. If for some reason you cannot do this, make sure that +org.el is loaded @emph{before} @file{allout.el}, for example by putting +@code{(require 'org)} early enough into your @file{.emacs} file. + @item @b{Org-mode seems to be a useful default mode for the various @file{README} files I have scattered through my directories. How do I -turn it on for all @file{README} files?}@* -@c +turn it on for all @file{README} files?} +@c @* + @example (add-to-list 'auto-mode-alist '("README$" . org-mode)) @end example @@ -3555,7 +3603,7 @@ convention that hides the link part and the brackets, only showing the description part. How can I convert my old links to this new format?}@* @c Execute once in each Org-mode file: @kbd{M-x org-upgrade-old-links}. -The replaces angular brackets with the link format. +This replaces angular brackets with the new link format. @item @b{I don't care if you find the new bracket links great, I am attached to the old style using angular brackets and no hiding of the @@ -3861,6 +3909,9 @@ control. @item Kevin Rogers contributed code to access VM files on remote hosts. @item +Frank Ruell solved the mystery of the @code{keymapp nil} bug, a conflict +with @file{allout.el}. +@item Philip Rooke created the Org-mode reference card and provided lots of feedback. @item Christian Schlauer proposed angular brackets around links, among other diff --git a/orgcard.pdf b/orgcard.pdf index 3053c1258..9c4b2674e 100644 Binary files a/orgcard.pdf and b/orgcard.pdf differ diff --git a/orgcard.tex b/orgcard.tex index 0ad90af0c..45608ac17 100644 --- a/orgcard.tex +++ b/orgcard.tex @@ -1,5 +1,5 @@ % Reference Card for Org Mode -\def\orgversionnumber{4.24} +\def\orgversionnumber{4.26} \def\year{2006} % %**start of header