diff --git a/org b/org index c71054178..3414c815f 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.13). + This manual is for Org-mode (version 4.19a). 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.13). +This manual is for Org-mode (version 4.19a). Copyright (C) 2004, 2005, 2006 Free Software Foundation @@ -51,6 +51,7 @@ This manual is for Org-mode (version 4.13). * 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 * Exporting:: Sharing and publishing of notes * Miscellaneous:: All the rest which did not fit elsewhere @@ -74,12 +75,12 @@ 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 -* Tags:: Tagging headlines and matching sets of tags * Plain Lists:: Editing hand-formatted lists Tables * Built-in table editor:: Simple tables +* Narrow columns:: Stop wasting space in tables * Table calculations:: Compute a field from other fields * orgtbl-mode:: The table editor as minor mode * table.el:: Complex tables @@ -95,6 +96,7 @@ Calculations in tables 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 @@ -124,6 +126,12 @@ Timestamps * Time stamps:: Assigning a time to a tree entry * Creating timestamps:: Commands which insert timestamps +Tags + +* Tag inheritance:: Tags use the tree structure of the outline +* Setting tags:: How to assign tags to a headline +* Tag searches:: Searching for combinations of tags + Agenda Views * Agenda files:: Files being searched for agenda information @@ -298,7 +306,6 @@ 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 -* Tags:: Tagging headlines and matching sets of tags * Plain Lists:: Editing hand-formatted lists  @@ -477,7 +484,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: Tags, Prev: Archiving, Up: Document Structure +File: org, Node: Sparse trees, Next: Plain Lists, Prev: Archiving, Up: Document Structure 2.7 Sparse trees ================ @@ -528,76 +535,9 @@ can then be printed in any desired way. display for outlining, not text properties  -File: org, Node: Tags, Next: Plain Lists, Prev: Sparse trees, Up: Document Structure +File: org, Node: Plain Lists, Prev: Sparse trees, Up: Document Structure -2.8 Tags -======== - -If you wish to implement a tag system to cross-correlate information, -this can be done as well in Org-mode. Every headline can contain a -list of tags, at the end of the headline. Tags are normal words -containing letters, numbers, `_', and `@'. Tags must be preceded and -followed by a single colon; like `:WORK:'. Several tags can be -specified like `:WORK:URGENT:'. - - Tags make use of the hierarchical structure of outline trees. If a -heading has a certain tag, all subheadings will inherit the tag as -well. For example, in the list - - * Meeting with the French group :WORK: - ** Summary by Frank :BOSS:NOTES: - *** TODO Prepare slides for him :ACTION: - the final heading will have the tags `:WORK:', `:BOSS:', `:NOTES:', -and `:ACTION:'. When executing tag searches and Org-mode finds that a -certain headline matches the search criterion, it will not check any -sublevel headline, assuming that these likely also match, and that the -list of matches can become very long. You can influence inheritance -and searching using the variables `org-use-tag-inheritance' and -`org-tags-match-list-sublevels'. - - Tags can simply be typed into the buffer. After a colon, `M-' -offers completion on all tags being used in the current buffer. There -are also special commands for inserting tags, and for executing -searches based on tags. - -`C-c C-c' - Enter new tags for the current headline. The minibuffer will - prompt for a list of tags and offer completion with respect to all - other tags used in the current buffer. Several tags, separated by - colons, may be specified at the prompt. After pressing , the - tags will be inserted and aligned to `org-tags-column'. When - called with a `C-u' prefix, align all tags in the current buffer - to that column, just to make things look nice. TAGS are - automatically realigned after promotion, demotion, and TODO state - changes (*note TODO basics::). - -`C-c \' - Create a sparse tree with all headlines matching a tags search. - -`C-c a m' - Create a global list of tag matches from all agenda files. *Note - Matching headline tags::. - -`C-c a M' - Create a global list of tag matches from all agenda files, but - check only TODO items and force checking subitems (see variable - `org-tags-match-list-sublevels'). - - A tags search string can use Boolean operators `&' for AND and `|' -for OR. `&' binds more strongly than `|'. Parenthesis are currently -not implemented. A tag may also be preceded by `-', to select against -it, and `+' is syntactic sugar for positive selection. The AND -operator `&' is optional when `+' or `-' is present. For example, -`+WORK-BOSS' would select all headlines that are tagged `:WORK:', but -discard those also tagged `:BOSS:'. The search string `WORK|LAPTOP' -selects all lines tagged `:WORK:' or `:LAPTOP:'. The string -`WORK|LAPTOP&NIGHT' requires that the `:LAPTOP:' lines are also tagged -`NIGHT'. - - -File: org, Node: Plain Lists, Prev: Tags, Up: Document Structure - -2.9 Plain Lists +2.8 Plain Lists =============== Headlines define both the structure of the Org-mode file, and also lists @@ -682,12 +622,13 @@ Emacs `calc' package. * Menu: * Built-in table editor:: Simple tables +* Narrow columns:: Stop wasting space in tables * Table calculations:: Compute a field from other fields * orgtbl-mode:: The table editor as minor mode * table.el:: Complex tables  -File: org, Node: Built-in table editor, Next: Table calculations, Prev: Tables, Up: Tables +File: org, Node: Built-in table editor, Next: Narrow columns, Prev: Tables, Up: Tables 3.1 The built-in table editor ============================= @@ -868,6 +809,10 @@ Calculations Miscellaneous ............. +`C-c `' + Edit the current field in a separate window. This is useful for + fields that are not fully visible (*note Narrow columns::). + `C-c |' Toggle the visibility of vertical lines in tables. The lines are still there, only made invisible with a text property. Any `|' @@ -895,9 +840,50 @@ off with manual re-align.  -File: org, Node: Table calculations, Next: orgtbl-mode, Prev: Built-in table editor, Up: Tables +File: org, Node: Narrow columns, Next: Table calculations, Prev: Built-in table editor, Up: Tables -3.2 Calculations in tables +3.2 Narrow columns +================== + +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 unconveniently 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 +characters. The next re-align will then set the width of this column +to no more than this value. + + |---+------------------------------| |---+--------| + | | | | | <6> | + | 1 | one | | 1 | one | + | 2 | two | ----\ | 2 | two | + | 3 | This is a long chunk of text | ----/ | 3 | This=> | + | 4 | four | | 4 | four | + |---+------------------------------| |---+--------| + Fields that are wider become clipped and end in the string `=>'. +Note that the full text is still in the buffer, it is only invisible. +To see the full text, hold the mouse over the field - a tooltip window +will show the full content. To edit such a field, use the command `C-c +`' (that is `C-c' followed by the backquote). This will open a new +window with the full field. Edit it and finish with `C-c C-c'. + + When visiting a file containing a table with narrowed columns, the +necessary character hiding has not yet happened, and the table needs to +be aligned before it looks nice. Setting the option +`org-startup-align-all-tables' will realign all tables in a file upon +visiting, but also slow down startup. You can also set this option on +a per-file basis with: + #+STARTUP: align + #+STARTUP: noalign + + ---------- Footnotes ---------- + + (1) This feature does not work on XEmacs. + + +File: org, Node: Table calculations, Next: orgtbl-mode, Prev: Narrow columns, Up: Tables + +3.3 Calculations in tables ========================== The table editor makes use of the Emacs `calc' package to implement @@ -922,7 +908,7 @@ own formula associated with them, and recalculation can be automated.  File: org, Node: Formula syntax, Next: Column formulas, Prev: Table calculations, Up: Table calculations -3.2.1 Formula syntax +3.3.1 Formula syntax -------------------- A formula can be any algebraic expression understood by the Emacs @@ -984,7 +970,7 @@ The default settings can be configured using the variable  File: org, Node: Column formulas, Next: Advanced features, Prev: Formula syntax, Up: Table calculations -3.2.2 Column formulas +3.3.2 Column formulas --------------------- To apply a formula to a field, type it directly into the field, @@ -1019,7 +1005,7 @@ separator line, assuming that this is the table header.  File: org, Node: Advanced features, Next: Named-field formulas, Prev: Column formulas, Up: Table calculations -3.2.3 Advanced features +3.3.3 Advanced features ----------------------- If you want the recalculation of fields to happen automatically, or if @@ -1091,7 +1077,7 @@ with empty first field.  File: org, Node: Named-field formulas, Next: Editing/debugging formulas, Prev: Advanced features, Up: Table calculations -3.2.4 Named-field formulas +3.3.4 Named-field formulas -------------------------- A named field can have its own formula associated with it. In the @@ -1105,7 +1091,7 @@ line) will also update all named field formulas.  File: org, Node: Editing/debugging formulas, Next: Appetizer, Prev: Named-field formulas, Up: Table calculations -3.2.5 Editing and debugging formulas +3.3.5 Editing and debugging formulas ------------------------------------ To edit a column or field formula, use the commands `C-c =' and `C-u @@ -1141,7 +1127,7 @@ will be displayed.  File: org, Node: Appetizer, Prev: Editing/debugging formulas, Up: Table calculations -3.2.6 Appetizer +3.3.6 Appetizer --------------- Finally, just to wet your appetite on what can be done with the @@ -1163,7 +1149,7 @@ series for a couple of functions (homework: try that with Excel :-)  File: org, Node: orgtbl-mode, Next: table.el, Prev: Table calculations, Up: Tables -3.3 The Orgtbl minor mode +3.4 The Orgtbl minor mode ========================= If you like the intuitive way the Org-mode table editor works, you @@ -1176,7 +1162,7 @@ in mail mode, use  File: org, Node: table.el, Prev: orgtbl-mode, Up: Tables -3.4 The `table.el' package +3.5 The `table.el' package ========================== Complex ASCII tables with automatic line wrapping, column- and @@ -1209,6 +1195,7 @@ links to other files, Usenet articles, emails and much more. * Menu: +* 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 @@ -1216,21 +1203,50 @@ links to other files, Usenet articles, emails and much more. * Remember:: Org-trees store quick notes  -File: org, Node: Internal links, Next: External links, Prev: Hyperlinks, Up: Hyperlinks +File: org, Node: Link format, Next: Internal links, Prev: Hyperlinks, Up: Hyperlinks -4.1 Internal links +4.1 Link format +=============== + +Org-mode will recognize plain URL-like links in the buffer and activate +them as clickable links. However, the general linkformat in Org-mode +looks like: + [[link][description]] or alternatively [[link]] + The description part is optional. Once a link in the buffer is +complete, Org-mode will change the display so that `description'( is +displayed instead of `[[link][description]]' and `link' is displayed +instead of `[[link]]'. Links will be highlighted in the face +`org-link', which by default is an underlined face. You can directly +edit the visible part of a link. To edit the invisible part, use `C-c +C-l' with the cursor on the link(1). + + ---------- Footnotes ---------- + + (1) You can also position the cursor directly after the link and +press to remove the (invisible) closing bracket `]'. This +makes the link incomplete, and shows the full raw link text for you to +edit. You may also use the menu entry `Org->Hperlinks->Literal links' +to unhide all links. + + +File: org, Node: Internal links, Next: External links, Prev: Link format, Up: Hyperlinks + +4.2 Internal links ================== -Strings inside double brackets like `[[My Target]]' are links that lead -to a text search in the current file. The link can be followed with -`C-c C-o' 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 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 no dedicated target exists, Org-mode will search for the words in -the link, in the above example for `my target'. Links starting with a +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 @@ -1238,12 +1254,12 @@ Targets]]' will find any of the following: ** My targets ** TODO my targets are bright ** my 20 targets are - It is therefore often not necessary to set a dedicated target. 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 creating -links. + + 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 +creating links. Following a link pushes a mark onto Org-mode's own mark ring. You can return to the previous position with `C-c &'. Using this command @@ -1258,7 +1274,7 @@ earlier.  File: org, Node: Radio targets, Next: CamelCase links, Prev: Internal links, Up: Internal links -4.1.1 Radio targets +4.2.1 Radio targets ------------------- You can configure Org-mode to link any occurrences of certain target @@ -1274,7 +1290,7 @@ on or at a target.  File: org, Node: CamelCase links, Prev: Radio targets, Up: Internal links -4.1.2 CamelCase words as links +4.2.2 CamelCase words as links ------------------------------ As an alternative to `[[...]]' links, Org-mode also supports CamelCase @@ -1288,12 +1304,12 @@ CamelCase version of headlines, the following customization is needed:  File: org, Node: External links, Next: Managing links, Prev: Internal links, Up: Hyperlinks -4.2 External links +4.3 External links ================== Org-mode supports links to files, websites, Usenet and email messages; -and BBDB database entries. Links are just plain-text URL-like -locators, optionally enclosed by angular brackets. The following list +and BBDB database entries. External links are plain-text URL-like +locators, optionally enclosed in angular brackets. The following list shows examples for each link type. on the web @@ -1319,7 +1335,13 @@ shows examples for each link type. the end of a line. In tables, the end of a table field also terminates a link. Angle brackets around a link are not required, but are recommended to avoid problems with punctuation and other text following -the link. See also the variable `org-allow-space-in-links'. +the link. + + To display a descriptive text instead of the URL, enclose the link +into double brackets and add the descriptive text like this: + [[][GNU Emacs]] + Links inserted with `C-c C-l' automatically use the double bracket +format (*note Managing links::). ---------- Footnotes ---------- @@ -1329,7 +1351,7 @@ a shell command. If you need redirection, use @{ and @} instead.  File: org, Node: Managing links, Next: Search Options, Prev: External links, Up: Hyperlinks -4.3 Managing links +4.4 Managing links ================== Org-mode provides methods to create a link in the correct syntax, to @@ -1351,12 +1373,13 @@ insert it into an org-mode file, and to follow the link. `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 one of the link type - prefixes mentioned in the examples above. Through completion, all - links stored during the current session can be accessed. When - called with prefix arg, you can use file name completion to enter - a file link. The link will be formatted as given in the variable - `org-link-format' and inserted into the buffer. Note that you + 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. When called with prefix arg, you can use + file name completion to enter a file link. 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. @@ -1365,7 +1388,7 @@ insert it into an org-mode file, and to follow the link. Open link at point. This will launch a web browser for URLs (using `browse-url-at-point'), run vm/gnus/bbdb for the corresponding links, and execute the command in a shell link. When the cursor - is on a CamelCase link, this commands runs the corresponding + is on am internal link, this commands runs the corresponding search. When the cursor is on a TAGS list in a headline, it creates the corresponding TAGS view. Furthermore, it will visit text files in `file:' links with Emacs and select a suitable @@ -1400,7 +1423,7 @@ insert it into an org-mode file, and to follow the link.  File: org, Node: Search Options, Next: Remember, Prev: Managing links, Up: Hyperlinks -4.4 Search options in file links +4.5 Search options in file links ================================ File links can contain additional information to make Emacs jump to a @@ -1441,7 +1464,7 @@ single colon.  File: org, Node: Remember, Prev: Search Options, Up: Hyperlinks -4.5 Remember +4.6 Remember ============ Another way to create org entries with links to other files is through @@ -1612,12 +1635,15 @@ File: org, Node: TODO extensions, Next: Priorities, Prev: Progress logging, 5.3 Extended use of TODO keywords ================================= -The default implementation of TODO entries is just two states: TODO -and DONE. You can, however, use the TODO feature for more complicated +The default implementation of TODO entries is just two states: TODO and +DONE. You can, however, use the TODO feature for more complicated things by configuring the variables `org-todo-keywords' and `org-todo-interpretation'. Using special setup, you can even use TODO keywords in different ways in different org files. + Note that tags are another way to classify headlines in general and +TODO items in particular (*note Tags::). + * Menu: * Workflow states:: From TODO to DONE in steps @@ -1754,7 +1780,7 @@ agenda (*note Weekly/Daily Agenda::). Interaction::).  -File: org, Node: Timestamps, Next: Agenda Views, Prev: TODO items, Up: Top +File: org, Node: Timestamps, Next: Tags, Prev: TODO items, Up: Top 6 Timestamps ************ @@ -1919,16 +1945,112 @@ date can be selected with the following commands: Choose date in calendar (only if nothing typed into minibuffer).  -File: org, Node: Agenda Views, Next: Exporting, Prev: Timestamps, Up: Top +File: org, Node: Tags, Next: Agenda Views, Prev: Timestamps, Up: Top -7 Agenda Views +7 Tags +****** + +If you wish to implement a system to cross-correlate information, an +excellent ways is assigning tags to headline. Org-mode has extensive +support for using tags. + + Every headline can contain a list of tags, at the end of the +headline. Tags are normal words containing letters, numbers, `_', and +`@'. Tags must be preceded and followed by a single colon; like +`:WORK:'. Several tags can be specified like `:WORK:URGENT:'. + +* Menu: + +* Tag inheritance:: Tags use the tree structure of the outline +* Setting tags:: How to assign tags to a headline +* Tag searches:: Searching for combinations of tags + + +File: org, Node: Tag inheritance, Next: Setting tags, Prev: Tags, Up: Tags + +7.1 Tag inheritance +=================== + +Tags make use of the hierarchical structure of outline trees. If a +heading has a certain tag, all subheadings will inherit the tag as +well. For example, in the list + + * Meeting with the French group :WORK: + ** Summary by Frank :BOSS:NOTES: + *** TODO Prepare slides for him :ACTION: + the final heading will have the tags `:WORK:', `:BOSS:', `:NOTES:', +and `:ACTION:'. When executing tag searches and Org-mode finds that a +certain headline matches the search criterion, it will not check any +sublevel headline, assuming that these likely also match, and that the +list of matches can become very long. However, this may not be what +you want, and you can influence inheritance and searching using the +variables `org-use-tag-inheritance' and `org-tags-match-list-sublevels'. + + +File: org, Node: Setting tags, Next: Tag searches, Prev: Tag inheritance, Up: Tags + +7.2 Setting tags +================ + +As Org-mode deals with plain text files, tags can simply be typed into +the buffer. After a colon, `M-' offers completion on all tags +being used in the current buffer. There is also a special command for +inserting tags: + +`C-c C-c' + Enter new tags for the current headline. The minibuffer will + prompt for a list of tags and offer completion with respect to all + other tags used in the current buffer. Several tags, separated by + colons, may be specified at the prompt. After pressing , the + tags will be inserted and aligned to `org-tags-column'. When + called with a `C-u' prefix, all tags in the current buffer will be + aligned to that column, just to make things look nice. TAGS are + automatically realigned after promotion, demotion, and TODO state + changes (*note TODO basics::). + + +File: org, Node: Tag searches, Prev: Setting tags, Up: Tags + +7.3 Tag searches +================ + +Once a tags system has been set up, it can be used to collect related +information into special lists. + +`C-c \' + Create a sparse tree with all headlines matching a tags search. + +`C-c a m' + Create a global list of tag matches from all agenda files. *Note + Matching headline tags::. + +`C-c a M' + Create a global list of tag matches from all agenda files, but + check only TODO items and force checking subitems (see variable + `org-tags-match-list-sublevels'). + + A tags search string can use Boolean operators `&' for AND and `|' +for OR. `&' binds more strongly than `|'. Parenthesis are currently +not implemented. A tag may also be preceded by `-', to select against +it, and `+' is syntactic sugar for positive selection. The AND +operator `&' is optional when `+' or `-' is present. For example, +`+WORK-BOSS' would select all headlines that are tagged `:WORK:', but +discard those also tagged `:BOSS:'. The search string `WORK|LAPTOP' +selects all lines tagged `:WORK:' or `:LAPTOP:'. The string +`WORK|LAPTOP&NIGHT' requires that the `:LAPTOP:' lines are also tagged +`NIGHT'. + + +File: org, Node: Agenda Views, Next: Exporting, Prev: Tags, Up: Top + +8 Agenda Views ************** -Due to the way Org-mode works, TODO items and time-stamped items can be -scattered throughout a file or even a number of files. To get an -overview over open action items, or over events that are important for -a particular date, this information must be collected, sorted and -displayed in an organized way. +Due to the way Org-mode works, TODO items, time-stamped items, and +tagged headlines can be scattered throughout a file or even a number of +files. To get an overview over open action items, or over events that +are important for a particular date, this information must be collected, +sorted and displayed in an organized way. Org-mode can select items based on various criteria, and display them in a separate buffer. Three different views are provided: @@ -1957,7 +2079,7 @@ edit these files remotely.  File: org, Node: Agenda files, Next: Agenda dispatcher, Prev: Agenda Views, Up: Agenda Views -7.1 Agenda files +8.1 Agenda files ================ The information to be shown is collected from all _agenda files_, the @@ -1992,13 +2114,13 @@ command will actually limit the command to the current file, and ignore  File: org, Node: Agenda dispatcher, Next: Weekly/Daily Agenda, Prev: Agenda files, Up: Agenda Views -7.2 The agenda dispatcher +8.2 The agenda dispatcher ========================= The views are created through a dispatcher that should be bound to a global key, for example `C-c a' (*note Installation and activation::). In the following we will assume that `C-c a' is indeed how the -dispatcher is accessed and lists keyboard access to commands +dispatcher is accessed and list keyboard access to commands accordingly. After pressing `C-c a', an additional letter is required to execute a command. The dispatcher offers the following default commands: @@ -2039,7 +2161,7 @@ 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 -7.3 The weekly/daily agenda +8.3 The weekly/daily agenda =========================== The purpose of the weekly/daily _agenda_ is to act like a page of a @@ -2067,7 +2189,7 @@ buffer. The commands available in the Agenda buffer are listed in  File: org, Node: Categories, Next: Time-of-day specifications, Prev: Weekly/Daily Agenda, Up: Weekly/Daily Agenda -7.3.1 Categories +8.3.1 Categories ---------------- In the agenda buffer, each entry is preceded by a _category_, which is @@ -2082,7 +2204,7 @@ 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 -7.3.2 Time-of-Day Specifications +8.3.2 Time-of-Day Specifications -------------------------------- Org-mode checks each agenda item for a time-of-day specification. The @@ -2127,7 +2249,7 @@ timed entries are embedded in a time grid, like  File: org, Node: Calendar/Diary integration, Next: Sorting of agenda items, Prev: Time-of-day specifications, Up: Weekly/Daily Agenda -7.3.3 Calendar/Diary integration +8.3.3 Calendar/Diary integration -------------------------------- Emacs contains the calendar and diary by Edward M. Reingold. The @@ -2155,7 +2277,7 @@ forth between calendar and agenda.  File: org, Node: Sorting of agenda items, Prev: Calendar/Diary integration, Up: Weekly/Daily Agenda -7.3.4 Sorting of agenda items +8.3.4 Sorting of agenda items ----------------------------- The entries for each day are sorted. The default order is to first @@ -2175,7 +2297,7 @@ increments for overdue scheduled or deadline items.  File: org, Node: Global TODO list, Next: Matching headline tags, Prev: Weekly/Daily Agenda, Up: Agenda Views -7.4 The global TODO list +8.4 The global TODO list ======================== The global TODO list contains all unfinished TODO items, formatted and @@ -2207,7 +2329,7 @@ list are described in *Note Agenda commands::.  File: org, Node: Matching headline tags, Next: Timeline, Prev: Global TODO list, Up: Agenda Views -7.5 Matching headline tags +8.5 Matching headline tags ========================== If headlines in the agenda files are marked with _tags_ (*note Tags::), @@ -2232,7 +2354,7 @@ Agenda commands::.  File: org, Node: Timeline, Next: Agenda commands, Prev: Matching headline tags, Up: Agenda Views -7.6 Timeline for a single file +8.6 Timeline for a single file ============================== The timeline is not really an agenda view, because it only summarizes @@ -2252,7 +2374,7 @@ Agenda commands::.  File: org, Node: Agenda commands, Prev: Timeline, Up: Agenda Views -7.7 Commands in the agenda buffer +8.7 Commands in the agenda buffer ================================= Entries in the agenda buffer are linked back to the org file or diary @@ -2445,7 +2567,7 @@ Quit and Exit  File: org, Node: Exporting, Next: Miscellaneous, Prev: Agenda Views, Up: Top -8 Exporting +9 Exporting *********** For printing and sharing of notes, Org-mode documents can be exported @@ -2462,7 +2584,7 @@ iCal, Org-mode can also produce extracts in the iCalendar format.  File: org, Node: ASCII export, Next: HTML export, Prev: Exporting, Up: Exporting -8.1 ASCII export +9.1 ASCII export ================ `C-c C-x a' @@ -2484,7 +2606,7 @@ not be exported.  File: org, Node: HTML export, Next: iCalendar export, Prev: ASCII export, Up: Exporting -8.2 HTML export +9.2 HTML export =============== Org-mode contains an HTML exporter with extensive HTML formatting, in @@ -2520,7 +2642,7 @@ example,  File: org, Node: HTML formatting, Next: Export options, Prev: HTML export, Up: HTML export -8.2.1 HTML formatting +9.2.1 HTML formatting --------------------- Not all text is transferred literally to the exported HTML file. The @@ -2561,7 +2683,7 @@ they can all be turned off with corresponding variables.  File: org, Node: Export options, Next: Comment lines, Prev: HTML formatting, Up: HTML export -8.2.2 Export options +9.2.2 Export options -------------------- The exporter recognizes special lines in the buffer which provide @@ -2612,7 +2734,7 @@ the new style visible to Emacs.  File: org, Node: Comment lines, Prev: Export options, Up: HTML export -8.2.3 Comment lines +9.2.3 Comment lines ------------------- Lines starting with `#' in column zero are treated as comments and will @@ -2627,7 +2749,7 @@ export.  File: org, Node: iCalendar export, Prev: HTML export, Up: Exporting -8.3 iCalendar export +9.3 iCalendar export ==================== Some people like to use Org-mode for keeping track of projects, but @@ -2672,8 +2794,8 @@ this:  File: org, Node: Miscellaneous, Next: Index, Prev: Exporting, Up: Top -9 Miscellaneous -*************** +10 Miscellaneous +**************** * Menu: @@ -2689,8 +2811,8 @@ File: org, Node: Miscellaneous, Next: Index, Prev: Exporting, Up: Top  File: org, Node: Completion, Next: Customization, Prev: Miscellaneous, Up: Miscellaneous -9.1 Completion -============== +10.1 Completion +=============== Org-mode supports in-buffer completion. This type of completion does not make use of the minibuffer. You simply type a few letters into the @@ -2717,8 +2839,8 @@ buffer and use the key to complete text right there.  File: org, Node: Customization, Next: Clean view, Prev: Completion, Up: Miscellaneous -9.2 Customization -================= +10.2 Customization +================== There are more than 100 variables that can be used to customize Org-mode. For the sake of compactness of the manual, we are not @@ -2729,12 +2851,12 @@ Group' from the `Org->Customization' menu.  File: org, Node: Clean view, Next: TTY keys, Prev: Customization, Up: Miscellaneous -9.3 A cleaner outline view -========================== +10.3 A cleaner outline view +=========================== Some people find it noisy and distracting that the Org-mode headlines -are starting with a potentially large number of stars. For example in -the example tree from *Note Headlines::: +are starting with a potentially large number of stars. For example the +tree from *Note Headlines::: * Top level headline ** Second level @@ -2811,8 +2933,8 @@ of the tree.  File: org, Node: TTY keys, Next: FAQ, Prev: Clean view, Up: Miscellaneous -9.4 Using org-mode on a tty -=========================== +10.4 Using org-mode on a tty +============================ Org-mode uses a number of keys that are not accessible on a tty. This applies to most special keys like cursor keys, and , when @@ -2853,8 +2975,8 @@ Default Alternative 1 Alternative 2  File: org, Node: FAQ, Next: Interaction, Prev: TTY keys, Up: Miscellaneous -9.5 Frequently asked questions -============================== +10.5 Frequently asked questions +=============================== 1. Org-mode seems to be a useful default mode for the various `README' files I have scattered through my directories. How do I @@ -2873,11 +2995,7 @@ File: org, Node: FAQ, Next: Interaction, Prev: TTY keys, Up: Miscellaneous `make-indirect-buffer'. In XEmacs, this is currently not possible because of the different outline implementation. - 4. Is there an easy way to insert links to web locations? - Sure, just type or paste them into the buffer. A plain-text - URL-like string is directly interpreted as a link. - - 5. When I export my TODO list, every TODO item becomes a separate + 4. 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 @@ -2895,42 +3013,42 @@ File: org, Node: FAQ, Next: Interaction, Prev: TTY keys, Up: Miscellaneous +OPTIONS: H:2; ... - 6. I would like to export only a subtree of my file to HTML. How? + 5. 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. - 7. Org-mode takes over the S-cursor keys. I also want to use + 6. 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::. - 8. Is there an easy way to insert an empty table template with a + 7. Is there an easy way to insert an empty table template with a default number of rows and columns? To insert an empty table template, just type `|-' and use . The default size can be changed with the variable `org-table-default-size'. However, just starting to type the first line is usually much easier. - 9. One of my table columns has started to fill up with `#ERROR'. + 8. 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 `#+TBLFMT:' 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! - 10. When I am in the last column of a table and just above a + 9. 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'. - 11. How can I change the indentation of an entire table without fixing + 10. 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 . - 12. Is it possible to include entries from org-mode files into my + 11. 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 @@ -2964,8 +3082,8 @@ File: org, Node: FAQ, Next: Interaction, Prev: TTY keys, Up: Miscellaneous  File: org, Node: Interaction, Next: Bugs, Prev: FAQ, Up: Miscellaneous -9.6 Interaction with other packages -=================================== +10.6 Interaction with other packages +==================================== Org-mode can cooperate with the following packages: @@ -2992,8 +3110,8 @@ Org-mode can cooperate with the following packages: `constants.el' by Carsten Dominik In a table formula (*note Table calculations::), it is possible to - use names for natural constants or units. Instead of defining you - own constants in the variable `org-table-formula-constants', + use names for natural constants or units. Instead of defining + your own constants in the variable `org-table-formula-constants', install the `constants' package which defines a large number of constants and units, and lets you use unit prefixes like `M' for `Mega' etc. You will need version 2.0 of this package, available @@ -3019,26 +3137,27 @@ Org-mode can cooperate with the following packages: `remember.el' by John Wiegley Org mode cooperates with remember, see *Note Remember::. - `Remember.el' is not part of Emacs, find it on the web. - -`planner.el' by John Wiegley - Planner is another tool to plan work and keep track of tasks. - Planner uses a multi-file approach with project pages and day - pages. Is it based on Emacs-Wiki. If Planner is your primary - tool, it can be useful to display the agenda entries resulting - from org files in day-pages of the planner. This can be done - through the diary of the calendar: integrate org files into the - diary as described above, and then turn on the diary support of - planner. Planner is not part of Emacs, find it on the web. + `Remember.el' is not part of Emacs, find it on the web.  File: org, Node: Bugs, Next: Acknowledgments, Prev: Interaction, Up: Miscellaneous -9.7 Bugs -======== +10.7 Bugs +========= -Here is a list of things which should work differently, but which I -have found too hard to fix. +Here is a list of things that should work differently, but which I have +found too hard to fix. + + * If a table field starts with a link, and if the corresponding table + column is narrowed (*note Narrow columns::) to a width too small to + display the link, the field would look entirely empty even though + it is not. To prevent this, Org-mode throws an error. The + work-around is to make the column wide enough to fit the link, or + to add some text (at least 2 characters) before the link in the + same field. + + * Narrowing table columns does not work on XEmacs, because the + `format' function does not transport text properties. * Text in an entry protected with the `QUOTE' keyword should not autowrap. @@ -3077,8 +3196,8 @@ have found too hard to fix.  File: org, Node: Acknowledgments, Prev: Bugs, Up: Miscellaneous -9.8 Acknowledgments -=================== +10.8 Acknowledgments +==================== Org-mode was written by Carsten Dominik, who still maintains it at the Org-mode homepage `http://www.astro.uva.nl/~dominik/Tools/org/'. The @@ -3115,6 +3234,9 @@ Org-mode would not be what it is without your input. * Oliver Oppitz suggested multi-state TODO items. + * Scott Otterson sparked the introduction of descriptive text for + links, among other things. + * Pete Phillips helped the development of the TAGS feature. * Matthias Rempe (Oelde) provided ideas, Windows support, and quality @@ -3139,7 +3261,10 @@ Org-mode would not be what it is without your input. * David Wainberg suggested archiving, and improvements to the linking system. - * Scheduling TODO items was inspired by John Wiegley's `planner.el'. + * Org-mode's linking system was an independent development, but with + time has evolved to work similar to John's implementation in + `emacs-wiki-mode'. In particular, I adopted his way to make the + link itself invisible and only show descriptive text. * Carsten Wimmer suggested some changes and helped fix a bug in linking to GNUS. @@ -3153,7 +3278,7 @@ Org-mode would not be what it is without your input.  File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top -10 Index +11 Index ******** [index] @@ -3208,7 +3333,7 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * completion, of option keywords: Export options. (line 6) * Completion, of option keywords: Per file keywords. (line 17) * completion, of tags <1>: Completion. (line 6) -* completion, of tags: Tags. (line 34) +* completion, of tags: Setting tags. (line 12) * completion, of TeX symbols <1>: Completion. (line 6) * completion, of TeX symbols: HTML formatting. (line 17) * completion, of TODO keywords <1>: Completion. (line 6) @@ -3242,7 +3367,7 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * emphasized text: Export options. (line 21) * evaluate time range: Creating timestamps. (line 63) * exporting: Exporting. (line 6) -* exporting a subtree: FAQ. (line 46) +* exporting a subtree: FAQ. (line 42) * exporting, not: Comment lines. (line 6) * extended TODO keywords: TODO extensions. (line 6) * external links: External links. (line 6) @@ -3257,8 +3382,9 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * fixed-width sections: Export options. (line 21) * folded, subtree visibility state: Visibility cycling. (line 10) * folding, sparse trees: Sparse trees. (line 6) -* following links: Managing links. (line 35) +* following links: Managing links. (line 36) * format specifier: Formula syntax. (line 34) +* format, of links: Link format. (line 6) * formula editing: Editing/debugging formulas. (line 6) * formula syntax: Formula syntax. (line 6) @@ -3286,9 +3412,9 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * HTML tags: HTML formatting. (line 33) * hyperlinks: Hyperlinks. (line 6) * iCalendar export: iCalendar export. (line 6) -* indentation, of tables: FAQ. (line 77) +* indentation, of tables: FAQ. (line 73) * indirect buffers: FAQ. (line 18) -* inheritance, of tags: Tags. (line 13) +* inheritance, of tags: Tag inheritance. (line 6) * inserting links: Managing links. (line 23) * installation: Installation and activation. (line 6) @@ -3301,16 +3427,17 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * keyword options: Per file keywords. (line 6) * linebreak preservation: Export options. (line 21) * link completion: Managing links. (line 23) +* link format: Link format. (line 6) * links, external: External links. (line 6) * links, internal: Internal links. (line 6) -* links, returning to: Managing links. (line 65) +* links, returning to: Managing links. (line 66) * lists, hand-formatted: HTML formatting. (line 9) * 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 18) -* mark ring: Managing links. (line 61) +* mark ring: Managing links. (line 62) * marking characters, tables: Advanced features. (line 33) * matching, of tags: Matching headline tags. (line 6) @@ -3323,6 +3450,7 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * named field formula: Named-field formulas. (line 6) * names as TODO keywords: TODO types. (line 6) +* narrow columns in tables: Narrow columns. (line 6) * occur, command: Sparse trees. (line 6) * option keyword completion: Completion. (line 6) * options, for customization: Customization. (line 6) @@ -3341,7 +3469,6 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * pasting, of subtrees: Structure editing. (line 6) * per file keywords: Per file keywords. (line 6) * plain lists: Plain Lists. (line 6) -* planner.el: Interaction. (line 58) * printing sparse trees: Sparse trees. (line 37) * priorities: Priorities. (line 6) * priorities, of agenda items: Sorting of agenda items. @@ -3363,6 +3490,7 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * scheduling: Time stamps. (line 6) * search option in file links: Search Options. (line 6) * section-numbers: Export options. (line 21) +* setting tags: Setting tags. (line 6) * SHELL links: External links. (line 6) * show all, command: Visibility cycling. (line 23) * show all, global visibility state: Visibility cycling. (line 17) @@ -3388,13 +3516,14 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top (line 6) * table editor, table.el: table.el. (line 6) * table of contents: Export options. (line 21) -* table, empty template: FAQ. (line 56) +* table, empty template: FAQ. (line 52) * table.el <1>: Interaction. (line 13) * table.el: table.el. (line 6) * tables <1>: Export options. (line 21) * tables: Tables. (line 6) * tables, export to HTML: HTML formatting. (line 24) * tag completion: Completion. (line 6) +* tag searches: Tag searches. (line 6) * tags: Tags. (line 6) * tags view: Matching headline tags. (line 6) @@ -3427,7 +3556,6 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * types as TODO keywords: TODO types. (line 6) * underlined text: HTML formatting. (line 13) * URL links: External links. (line 6) -* URL, paste into buffer: FAQ. (line 24) * USENET links: External links. (line 6) * variables, for customization: Customization. (line 6) * vectors, in table calculations: Formula syntax. (line 23) @@ -3440,7 +3568,7 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top  File: org, Node: Key Index, Prev: Index, Up: Top -11 Key Index +12 Key Index ************ [index] @@ -3473,8 +3601,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 61) -* C-c &: Managing links. (line 65) +* C-c %: Managing links. (line 62) +* C-c &: Managing links. (line 66) * C-c ' <1>: Editing/debugging formulas. (line 20) * C-c ': Built-in table editor. @@ -3499,37 +3627,39 @@ File: org, Node: Key Index, Prev: Index, Up: Top * C-c ?: Built-in table editor. (line 162) * C-c [: Agenda files. (line 12) -* C-c \: Tags. (line 42) +* C-c \: Tag searches. (line 9) * C-c ]: Agenda files. (line 15) * C-c ^: Built-in table editor. (line 97) +* C-c `: Built-in table editor. + (line 182) * 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) * C-c a m: Matching headline tags. (line 10) -* C-c a M: Tags. (line 49) -* C-c a m: Tags. (line 45) +* C-c a M: Tag searches. (line 14) +* C-c a m: Tag searches. (line 10) * C-c a T: Global TODO list. (line 15) * C-c a t <1>: Global TODO list. (line 9) * C-c a t: TODO basics. (line 25) * C-c C-a: Visibility cycling. (line 23) * C-c C-b: Motion. (line 15) -* C-c C-c <1>: table.el. (line 6) -* C-c C-c <2>: Editing/debugging formulas. +* C-c C-c <1>: Setting tags. (line 11) +* C-c C-c <2>: table.el. (line 6) +* C-c C-c <3>: Editing/debugging formulas. (line 16) -* C-c C-c <3>: Built-in table editor. +* C-c C-c <4>: Built-in table editor. (line 43) -* C-c C-c <4>: Plain Lists. (line 61) -* C-c C-c: Tags. (line 33) +* C-c C-c: Plain Lists. (line 61) * 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-n: Motion. (line 8) * C-c C-o <1>: Creating timestamps. (line 33) -* C-c C-o: Managing links. (line 35) +* C-c C-o: Managing links. (line 36) * C-c C-p: Motion. (line 9) * C-c C-q <1>: Editing/debugging formulas. (line 20) @@ -3563,7 +3693,7 @@ File: org, Node: Key Index, Prev: Index, Up: Top * C-c C-y: Creating timestamps. (line 63) * C-c l: Managing links. (line 9) * C-c |: Built-in table editor. - (line 182) + (line 186) * C-c ~: table.el. (line 18) * C-u C-c .: Creating timestamps. (line 16) * C-u C-c =: Built-in table editor. @@ -3588,8 +3718,8 @@ File: org, Node: Key Index, Prev: Index, Up: Top (line 73) * M-: Structure editing. (line 16) * M- <1>: Completion. (line 10) -* M- <2>: Per file keywords. (line 17) -* M-: Tags. (line 28) +* M- <2>: Setting tags. (line 6) +* M-: Per file keywords. (line 17) * M-: Built-in table editor. (line 83) * M-S- <1>: Built-in table editor. @@ -3613,11 +3743,11 @@ File: org, Node: Key Index, Prev: Index, Up: Top * M-S-: Structure editing. (line 25) * mouse-1 <1>: Agenda commands. (line 35) * mouse-1 <2>: Creating timestamps. (line 79) -* mouse-1: Managing links. (line 53) +* mouse-1: Managing links. (line 54) * mouse-2 <1>: Agenda commands. (line 35) -* mouse-2: Managing links. (line 53) +* mouse-2: Managing links. (line 54) * mouse-3 <1>: Agenda commands. (line 28) -* mouse-3: Managing links. (line 58) +* mouse-3: Managing links. (line 59) * n: Agenda commands. (line 19) * o: Agenda commands. (line 57) * P: Agenda commands. (line 115) @@ -3649,91 +3779,98 @@ File: org, Node: Key Index, Prev: Index, Up: Top  Tag Table: -Node: Top959 -Node: Introduction6836 -Node: Summary7150 -Node: Installation and activation9262 -Node: Feedback10931 -Node: Document Structure11716 -Node: Outlines12558 -Node: Headlines13218 -Node: Visibility cycling13844 -Node: Motion15031 -Node: Structure editing15815 -Node: Archiving17558 -Node: Sparse trees18418 -Ref: Sparse trees-Footnote-120441 -Ref: Sparse trees-Footnote-220533 -Node: Tags20647 -Node: Plain Lists23739 -Ref: Plain Lists-Footnote-126487 -Node: Tables26844 -Node: Built-in table editor27331 -Node: Table calculations34874 -Node: Formula syntax36057 -Ref: Formula syntax-Footnote-138990 -Node: Column formulas39289 -Node: Advanced features41051 -Node: Named-field formulas44305 -Node: Editing/debugging formulas44945 -Node: Appetizer46703 -Node: orgtbl-mode47805 -Node: table.el48295 -Node: Hyperlinks49272 -Node: Internal links49838 -Node: Radio targets51588 -Node: CamelCase links52303 -Node: External links52876 -Ref: External links-Footnote-154802 -Node: Managing links54941 -Node: Search Options58276 -Ref: Search Options-Footnote-159589 -Node: Remember59670 -Ref: Remember-Footnote-163554 -Node: TODO items63678 -Node: TODO basics64601 -Node: Progress logging66114 -Node: TODO extensions66901 -Node: Workflow states67589 -Node: TODO types68457 -Ref: TODO types-Footnote-170115 -Node: Per file keywords70197 -Ref: Per file keywords-Footnote-171650 -Node: Priorities71878 -Node: Timestamps73087 -Node: Time stamps73416 -Node: Creating timestamps75431 -Node: Agenda Views78560 -Node: Agenda files80087 -Ref: Agenda files-Footnote-181049 -Ref: Agenda files-Footnote-281198 -Node: Agenda dispatcher81390 -Node: Weekly/Daily Agenda83522 -Node: Categories84657 -Node: Time-of-day specifications85303 -Node: Calendar/Diary integration87279 -Node: Sorting of agenda items88658 -Node: Global TODO list89490 -Node: Matching headline tags90905 -Node: Timeline91848 -Node: Agenda commands92723 -Node: Exporting97978 -Node: ASCII export98550 -Node: HTML export99386 -Node: HTML formatting100503 -Node: Export options102135 -Node: Comment lines104328 -Node: iCalendar export104798 -Node: Miscellaneous106593 -Node: Completion107218 -Node: Customization108212 -Node: Clean view108658 -Node: TTY keys111309 -Node: FAQ112908 -Node: Interaction117794 -Node: Bugs121202 -Node: Acknowledgments122944 -Node: Index125364 -Node: Key Index145568 +Node: Top960 +Node: Introduction7181 +Node: Summary7495 +Node: Installation and activation9607 +Node: Feedback11276 +Node: Document Structure12061 +Node: Outlines12827 +Node: Headlines13487 +Node: Visibility cycling14113 +Node: Motion15300 +Node: Structure editing16084 +Node: Archiving17827 +Node: Sparse trees18687 +Ref: Sparse trees-Footnote-120717 +Ref: Sparse trees-Footnote-220809 +Node: Plain Lists20923 +Ref: Plain Lists-Footnote-123679 +Node: Tables24036 +Node: Built-in table editor24584 +Node: Narrow columns32267 +Ref: Narrow columns-Footnote-134199 +Node: Table calculations34245 +Node: Formula syntax35421 +Ref: Formula syntax-Footnote-138354 +Node: Column formulas38653 +Node: Advanced features40415 +Node: Named-field formulas43669 +Node: Editing/debugging formulas44309 +Node: Appetizer46067 +Node: orgtbl-mode47169 +Node: table.el47659 +Node: Hyperlinks48636 +Node: Link format49270 +Ref: Link format-Footnote-150100 +Node: Internal links50403 +Node: Radio targets52291 +Node: CamelCase links53006 +Node: External links53579 +Ref: External links-Footnote-155750 +Node: Managing links55889 +Node: Search Options59290 +Ref: Search Options-Footnote-160603 +Node: Remember60684 +Ref: Remember-Footnote-164568 +Node: TODO items64692 +Node: TODO basics65615 +Node: Progress logging67128 +Node: TODO extensions67915 +Node: Workflow states68715 +Node: TODO types69583 +Ref: TODO types-Footnote-171241 +Node: Per file keywords71323 +Ref: Per file keywords-Footnote-172776 +Node: Priorities73004 +Node: Timestamps74213 +Node: Time stamps74534 +Node: Creating timestamps76549 +Node: Tags79678 +Node: Tag inheritance80414 +Node: Setting tags81353 +Node: Tag searches82315 +Node: Agenda Views83524 +Node: Agenda files85064 +Ref: Agenda files-Footnote-186026 +Ref: Agenda files-Footnote-286175 +Node: Agenda dispatcher86367 +Node: Weekly/Daily Agenda88498 +Node: Categories89633 +Node: Time-of-day specifications90279 +Node: Calendar/Diary integration92255 +Node: Sorting of agenda items93634 +Node: Global TODO list94466 +Node: Matching headline tags95881 +Node: Timeline96824 +Node: Agenda commands97699 +Node: Exporting102954 +Node: ASCII export103526 +Node: HTML export104362 +Node: HTML formatting105479 +Node: Export options107111 +Node: Comment lines109304 +Node: iCalendar export109774 +Node: Miscellaneous111569 +Node: Completion112196 +Node: Customization113192 +Node: Clean view113640 +Node: TTY keys116282 +Node: FAQ117883 +Node: Interaction122588 +Node: Bugs125427 +Node: Acknowledgments127736 +Node: Index130455 +Node: Key Index150878  End Tag Table diff --git a/org.el b/org.el index 5b252ff6b..dacfb5b88 100644 --- a/org.el +++ b/org.el @@ -5,9 +5,9 @@ ;; Author: Carsten Dominik ;; Keywords: outlines, hypermedia, calendar, wp ;; Homepage: http://www.astro.uva.nl/~dominik/Tools/org/ -;; Version: 4.13 +;; Version: 4.19a ;; -;; This file is part of GNU Emacs. +;; This file is part of GNU Emacs. ;; ;; GNU Emacs is free software; you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by @@ -81,6 +81,13 @@ ;; ;; Changes since version 4.00: ;; --------------------------- +;; Version 4.20 +;; - Links use now the [[link][description]] format by default. +;; When inserting links, the user is prompted for a description. +;; - If a link has a description, only the description is displayed +;; the link part is hidden. Use C-c C-l to edit the link part. +;; - TAGS are now bold, but in the same color as the headline. +;; ;; Version 4.13 ;; - The list of agenda files can be maintainted in an external file. ;; - Bug fixes. @@ -88,7 +95,7 @@ ;; Version 4.12 ;; - Templates for remember buffer. Note that the remember setup changes. ;; To set up templates, see `org-remember-templates'. -;; - The time in new time stamps can be rounded, see new option +;; - The time in new time stamps can be rounded, see new option ;; `org-time-stamp-rounding-minutes'. ;; - Bug fixes (there are *always* more bugs). ;; @@ -109,7 +116,7 @@ ;; - 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. @@ -159,7 +166,7 @@ ;;; Customization variables -(defvar org-version "4.13" +(defvar org-version "4.19a" "The version number of the file org.el.") (defun org-version () (interactive) @@ -169,6 +176,11 @@ ;; of outline.el. (defconst org-noutline-p (featurep 'noutline) "Are we using the new outline mode?") +(defconst org-format-transports-properties-p + (let ((x "a")) + (add-text-properties 0 1 '(test t) x) + (get-text-property 0 'test (format "%s" x))) + "Does format transport text properties?") (defgroup org nil "Outline-based notes management and organizer." @@ -182,6 +194,56 @@ :tag "Org Startup" :group 'org) +(defcustom org-startup-folded t + "Non-nil means, entering Org-mode will switch to OVERVIEW. +This can also be configured on a per-file basis by adding one of +the following lines anywhere in the buffer: + + #+STARTUP: fold + #+STARTUP: nofold + #+STARTUP: content" + :group 'org-startup + :type '(choice + (const :tag "nofold: show all" nil) + (const :tag "fold: overview" t) + (const :tag "content: all headlines" content))) + +(defcustom org-startup-truncated t + "Non-nil means, entering Org-mode will set `truncate-lines'. +This is useful since some lines containing links can be very long and +uninteresting. Also tables look terrible when wrapped." + :group 'org-startup + :type 'boolean) + +(defcustom org-startup-align-all-tables nil + "Non-nil means, allign all tables when visiting a file. +This is useful when the column width in tables is forced with cookies +in table fields. Such tables will look correct only after the first re-align." + :group 'org-startup + :type 'boolean) + +(defcustom org-startup-with-deadline-check nil + "Non-nil means, entering Org-mode will run the deadline check. +This means, if you start editing an org file, you will get an +immediate reminder of any due deadlines. +This can also be configured on a per-file basis by adding one of +the following lines anywhere in the buffer: + + #+STARTUP: dlcheck + #+STARTUP: nodlcheck" + :group 'org-startup + :type 'boolean) + +(defcustom org-insert-mode-line-in-empty-file nil + "Non-nil means insert the first line setting Org-mode in empty files. +When the function `org-mode' is called interactively in an empty file, this +normally means that the file name does not automatically trigger Org-mode. +To ensure that the file will always be in Org-mode in the future, a +line enforcing Org-mode will be inserted into the buffer, if this option +has been set." + :group 'org-startup + :type 'boolean) + (defcustom org-CUA-compatible nil "Non-nil means use alternative key bindings for S-. Org-mode used S- for changing timestamps and priorities. @@ -220,49 +282,6 @@ second element will be used when `org-CUA-compatible' is t.") (or (assq key org-disputed-keys) (error "Invalid Key %s in `org-key'" key)))) -(defcustom org-startup-folded t - "Non-nil means, entering Org-mode will switch to OVERVIEW. -This can also be configured on a per-file basis by adding one of -the following lines anywhere in the buffer: - - #+STARTUP: fold - #+STARTUP: nofold - #+STARTUP: content" - :group 'org-startup - :type '(choice - (const :tag "nofold: show all" nil) - (const :tag "fold: overview" t) - (const :tag "content: all headlines" content))) - -(defcustom org-startup-truncated t - "Non-nil means, entering Org-mode will set `truncate-lines'. -This is useful since some lines containing links can be very long and -uninteresting. Also tables look terrible when wrapped." - :group 'org-startup - :type 'boolean) - -(defcustom org-startup-with-deadline-check nil - "Non-nil means, entering Org-mode will run the deadline check. -This means, if you start editing an org file, you will get an -immediate reminder of any due deadlines. -This can also be configured on a per-file basis by adding one of -the following lines anywhere in the buffer: - - #+STARTUP: dlcheck - #+STARTUP: nodlcheck" - :group 'org-startup - :type 'boolean) - -(defcustom org-insert-mode-line-in-empty-file nil - "Non-nil means insert the first line setting Org-mode in empty files. -When the function `org-mode' is called interactively in an empty file, this -normally means that the file name does not automatically trigger Org-mode. -To ensure that the file will always be in Org-mode in the future, a -line enforcing Org-mode will be inserted into the buffer, if this option -has been set." - :group 'org-startup - :type 'boolean) - (defgroup org-keywords nil "Options concerning TODO items in Org-mode." :tag "Org Keywords" @@ -318,17 +337,6 @@ beginning of a headline." :type '(choice (const sequence) (const type))) -(defcustom org-default-priority ?B - "The default priority of TODO items. -This is the priority an item get if no explicit priority is given." - :group 'org-keywords - :type 'character) - -(defcustom org-lowest-priority ?C - "The lowest priority of TODO items. A character like ?A, ?B etc." - :group 'org-keywords - :type 'character) - (defcustom org-deadline-string "DEADLINE:" "String to mark deadline entries. A deadline is this string, followed by a time stamp. Should be a word, @@ -376,6 +384,17 @@ Lisp variable `state'." :group 'org-keywords :type 'hook) +(defcustom org-default-priority ?B + "The default priority of TODO items. +This is the priority an item get if no explicit priority is given." + :group 'org-keywords + :type 'character) + +(defcustom org-lowest-priority ?C + "The lowest priority of TODO items. A character like ?A, ?B etc." + :group 'org-keywords + :type 'character) + ;; Variables for pre-computed regular expressions, all buffer local (defvar org-todo-kwd-priority-p nil "Do TODO items have priorities?") @@ -833,7 +852,7 @@ This has the effect that two stars are being added/taken away in promotion/demotion commands. It also influences how levels are handled by the exporters. Changing it requires restart of `font-lock-mode' to become effective -for fontification also in regions already fontified." +for fontification also in regions already fontified." :group 'org-structure :group 'org-font-lock :type 'boolean) @@ -874,6 +893,12 @@ See also the QUOTE keyword." :group 'org-structure :type 'boolean) + +(defgroup org-archive nil + "Options concerning archiving in Org-mode." + :tag "Org Archive" + :group 'org) + (defcustom org-archive-location "%s_archive::" "The location where subtrees should be archived. This string consists of two parts, separated by a double-colon. @@ -907,12 +932,12 @@ You may set this option on a per-file basis by adding to the buffer a line like #+ARCHIVE: basement::** Finished Tasks" - :group 'org-structure + :group 'org-archive :type 'string) (defcustom org-archive-mark-done t "Non-nil means, mark archived entries as DONE." - :group 'org-structure + :group 'org-archive :type 'boolean) (defcustom org-archive-stamp-time t @@ -920,7 +945,7 @@ line like The time stamp will be added directly after the TODO state keyword in the first line, so it is probably best to use this in combinations with `org-archive-mark-done'." - :group 'org-structure + :group 'org-archive :type 'boolean) (defgroup org-tags nil @@ -977,6 +1002,20 @@ make sure all corresponding TODO items find their way into the list." :tag "Org Link" :group 'org) +(defcustom org-descriptive-links t + "Non-nil means, hide link part and only show description of bracket links. +Bracket links are like [[link][descritpion]]. This variable sets the initial +state in new org-mode buffers. The setting can then be toggled on a +per-buffer basis from the Org->Hyperlinks menu." + :group 'org-link + :type 'boolean) + +(defcustom org-old-link-style nil + "Non-nil means don't use bracket-style links when inserting a link. +Deprecated, the bracket-style link system is better and should be used." + :group 'org-link + :type 'boolean) + (defcustom org-tab-follows-link nil "Non-nil means, on links TAB will follow the link. Needs to be set before org.el is loaded." @@ -996,7 +1035,7 @@ Changing this requires a restart of Emacs to work correctly." :type 'interger) (defcustom org-link-format "<%s>" - "Default format for linkes in the buffer. + "Default format for external, URL-like linkes in the buffer. This is a format string for printf, %s will be replaced by the link text. If you want to make sure that your link is always properly terminated, include angle brackets into this format, like \"<%s>\". Some people also @@ -1008,6 +1047,7 @@ recommend an additional URL: prefix, so the format would be \"\"." (const :tag "\"\" (e.g. )" "") (string :tag "Other" :value "<%s>"))) +;; FIXME: What is the meaning of this in the age of bracket links???? (defcustom org-allow-space-in-links t "Non-nil means, file names in links may contain space characters. When nil, it becomes possible to put several links into a line. @@ -1043,7 +1083,8 @@ negates this setting for the duration of the command." (defcustom org-file-link-context-use-camel-case nil "Non-nil means, use CamelCase to store a search context in a file link. -When nil, the search string simply consists of the words of the string." +When nil, the search string simply consists of the words of the string. +CamelCase is deprecated, and support for it may be dropped in the future." :group 'org-link :type 'boolean) @@ -1178,9 +1219,9 @@ For more examples, see the system specific constants (sexp :tag "Lisp form"))))) (defcustom org-mhe-search-all-folders nil - "Non-nil means, that the search for the mh-message will be extended to + "Non-nil means, that the search for the mh-message will be extended to all folders if the message cannot be found in the folder given in the link. -Searching all folders is very effective with one of the search engines +Searching all folders is very effective with one of the search engines supported by MH-E, but will be slow with pick." :group 'org-link :type 'boolean) @@ -1228,7 +1269,7 @@ Furthermore, the following %-escapes will be replaced with content: If %i is indented, the entire inserted text will be indented as well. %? This will be removed, and the cursor placed at this position." :group 'org-remember - :type '(repeat :tag "enabled" + :type '(repeat :tag "enabled" (list :value (?a "\n" nil) (character :tag "Selection Key") (string :tag "Template") @@ -1374,6 +1415,11 @@ calls `table-recognize-table'." :group 'org-table :type 'boolean) +(defcustom org-table-limit-column-width t + "Non-nil means, allow to limit the width of table columns with fields." + :group 'org-table + :type 'boolean) + (defgroup org-table-calculation nil "Options concerning tables in Org-mode." :tag "Org Table Calculation" @@ -1796,8 +1842,6 @@ Changing this variable requires a restart of Emacs to take effect." (((type tty) (class color)) (:foreground "white")) (((class color) (background light)) (:foreground "white")) (((class color) (background dark)) (:foreground "black")) -; (((class color) (backgro6und light)) (:foreground "grey90")) -; (((class color) (background dark)) (:foreground "grey10")) (t (:inverse-video nil))) "Face used for level 1 headlines." :group 'org-font-lock) @@ -1893,7 +1937,7 @@ Changing this variable requires a restart of Emacs to take effect." `org-fontify-done-headline'." :group 'org-font-lock) -;; Inheritance does not yet work for xemacs. So we just copy... +;; Inheritance does not work for xemacs. So we just copy... (defface org-deadline-announce '((((type tty) (class color)) (:foreground "blue" :weight bold)) @@ -1931,16 +1975,16 @@ Changing this variable requires a restart of Emacs to take effect." (defface org-link '((((type tty) (class color)) (:foreground "cyan" :weight bold)) - (((class color) (background light)) (:foreground "Purple")) - (((class color) (background dark)) (:foreground "Cyan")) + (((class color) (background light)) (:foreground "Purple" :underline t)) + (((class color) (background dark)) (:foreground "Cyan" :underline t)) (t (:bold t))) "Face for links." :group 'org-font-lock) (defface org-tag - '((((type tty) (class color)) (:foreground "cyan" :weight bold)) - (((class color) (background light)) (:foreground "Purple" :weight bold)) - (((class color) (background dark)) (:foreground "Cyan" :weight bold)) + '((((type tty) (class color)) (:weight bold)) + (((class color) (background light)) (:weight bold)) + (((class color) (background dark)) (:weight bold)) (t (:bold t))) "Face for tags." :group 'org-font-lock) @@ -2012,6 +2056,8 @@ Changing this variable requires a restart of Emacs to take effect." ("showstars" org-hide-leading-stars nil) ("odd" org-odd-levels-only t) ("oddeven" org-odd-levels-only nil) + ("align" org-startup-align-all-tables t) + ("noalign" org-startup-align-all-tables nil) ("dlcheck" org-startup-with-deadline-check t) ("nodlcheck" org-startup-with-deadline-check nil))) l var val) @@ -2149,6 +2195,8 @@ The following commands are available: (easy-menu-add org-org-menu) (easy-menu-add org-tbl-menu) (org-install-agenda-files-menu) + (if org-descriptive-links (org-add-to-invisibility-spec '(org-link . nil))) + (org-add-to-invisibility-spec '(org-cwidth . nil)) (setq outline-regexp "\\*+") ; (setq outline-regexp "\\(?:\\*+\\|[ \t]*\\(?:[-+*]\\|[0-9]+[.)]\\) \\)") (setq outline-level 'org-outline-level) @@ -2185,6 +2233,8 @@ The following commands are available: (define-key org-mode-map [menu-bar show] 'undefined)) (unless org-inhibit-startup + (if org-startup-align-all-tables + (org-table-map-tables 'org-table-align)) (if org-startup-with-deadline-check (call-interactively 'org-check-deadlines) (cond @@ -2197,6 +2247,11 @@ The following commands are available: (defsubst org-current-line (&optional pos) (+ (if (bolp) 1 0) (count-lines (point-min) (or pos (point))))) +(defsubst org-match-string-no-properties (num &optional string) + (if (featurep 'xemacs) + (match-string num string) + (match-string-no-properties num string))) + (defun org-current-time () "Current time, possibly rounded to `org-time-stamp-rounding-minutes'." (if (> org-time-stamp-rounding-minutes 0) @@ -2230,6 +2285,7 @@ The following commands are available: (require 'font-lock) +;; FIXME: Can/should we add the brackets? (defconst org-non-link-chars "\t\n\r|<>\000") (defconst org-link-regexp (if org-allow-space-in-links @@ -2274,16 +2330,32 @@ The following commands are available: (progn (add-text-properties (match-beginning 0) (match-end 0) (list 'mouse-face 'highlight - 'keymap org-mouse-map)) + 'keymap org-mouse-map + )) t))) (defun org-activate-links2 (limit) - "Run through the buffer and add overlays to links." + "Run through the buffer and add overlays to bracketed links." (if (re-search-forward org-bracket-link-regexp limit t) - (progn - (add-text-properties (match-beginning 0) (match-end 0) - (list 'mouse-face 'highlight - 'keymap org-mouse-map)) + (let* ((help (concat "LINK: " (org-match-string-no-properties 1))) + (ip (list 'invisible 'org-link 'intangible t 'rear-nonsticky t + 'keymap org-mouse-map 'mouse-face 'highlight + 'help-echo help)) + (vp (list 'rear-nonsticky t + 'keymap org-mouse-map 'mouse-face 'highlight + 'help-echo help))) + ;; We need to remove the invisible property here, because + ;; of the table width code.... FIXME: explain better. + (remove-text-properties (match-beginning 0) (match-end 0) + '(invisible nil)) + (if (match-end 3) + (progn + (add-text-properties (match-beginning 0) (match-beginning 3) ip) + (add-text-properties (match-beginning 3) (match-end 3) vp) + (add-text-properties (match-end 3) (match-end 0) ip)) + (add-text-properties (match-beginning 0) (match-beginning 1) ip) + (add-text-properties (match-beginning 1) (match-end 1) vp) + (add-text-properties (match-end 1) (match-end 0) ip)) t))) (defun org-activate-dates (limit) @@ -2311,6 +2383,7 @@ The following commands are available: (add-text-properties (match-beginning 0) (match-end 0) (list 'mouse-face 'highlight 'keymap org-mouse-map + 'help-echo "Radio target link" 'org-linked-text t)) t))))) @@ -2320,6 +2393,22 @@ The following commands are available: (when org-radio-targets (setq org-target-link-regexp (org-make-target-link-regexp (org-all-targets 'radio))) + (org-restart-font-lock))) + +(defun org-hide-wide-columns (limit) + (when org-table-limit-column-width + (let (s e) + (setq s (text-property-any (point) (or limit (point-max)) + 'org-cwidth t)) + (when s + (setq e (next-single-property-change s 'org-cwidth)) + (add-text-properties s e '(invisible org-cwidth intangible t)) + (goto-char e) + t)))) + +(defun org-restart-font-lock () + "Restart font-lock-mode, to force refontification." + (when (and (boundp 'font-lock-mode) font-lock-mode) (font-lock-mode -1) (font-lock-mode 1))) @@ -2331,10 +2420,7 @@ With optional argument RADIO, only find radio targets." (save-excursion (goto-char (point-min)) (while (re-search-forward re nil t) - (add-to-list 'rtn (downcase - (if (fboundp 'match-string-no-properties) - (match-string-no-properties 1) - (match-string 1))))) + (add-to-list 'rtn (downcase (org-match-string-no-properties 1)))) rtn))) (defun org-make-target-link-regexp (targets) @@ -2394,21 +2480,24 @@ between words." (list '("^\\(\\**\\)\\(\\*\\)\\(.*\\)" (1 (org-get-level-face 1)) (2 (org-get-level-face 2)) (3 (org-get-level-face 3))) + '("^[ \t]*\\(\\(|\\|\\+-[-+]\\).*\\S-\\)" + (1 'org-table)) '(org-activate-links (0 'org-link t)) '(org-activate-links2 (0 'org-link t)) '(org-activate-target-links (0 'org-link t)) '(org-activate-dates (0 'org-link t)) '(org-activate-camels (0 'org-link t)) - '(org-activate-tags (1 'org-tag t)) + '(org-activate-tags (1 'org-tag append)) + '(org-hide-wide-columns (0 nil append)) (list (concat "^\\*+[ \t]*" org-not-done-regexp) '(1 'org-warning t)) (list (concat "\\[#[A-Z]\\]") '(0 'org-special-keyword t)) (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)) - (if em '("\\(\\W\\|^\\)\\(/\\w+/\\)\\(\\W\\|$\\)" 2 'italic)) - (if em '("\\(\\W\\|^\\)\\(_\\w+_\\)\\(\\W\\|$\\)" 2 'underline)) + (if em '("\\(\\W\\|^\\)\\(\\*\\w+\\*\\)\\(\\W\\|$\\)" 2 'bold append)) + (if em '("\\(\\W\\|^\\)\\(/\\w+/\\)\\(\\W\\|$\\)" 2 'italic append)) + (if em '("\\(\\W\\|^\\)\\(_\\w+_\\)\\(\\W\\|$\\)" 2 'underline append)) (list (concat "^\\*+[ \t]*\\<\\(" org-comment-string "\\|" org-quote-string "\\)\\>") '(1 'org-special-keyword t)) @@ -2418,11 +2507,11 @@ between words." '(1 'org-done t) '(2 'org-headline-done t)) (list (concat "^[*]+ +\\<\\(" org-done-string "\\)\\>") '(1 'org-done t))) - '("^[ \t]*\\(\\(|\\|\\+-[-+]\\).*\\S-\\)" - (1 'org-table t)) '("^[ \t]*\\(:.*\\)" (1 'org-table t)) '("| *\\(:?=[^|\n]*\\)" (1 'org-formula t)) '("^[ \t]*| *\\([#!$*_^]\\) *|" (1 'org-formula t)) + (if org-format-transports-properties-p + '("| *\\(<[0-9]+>\\) *|" (1 'org-formula t))) ))) (setq org-font-lock-extra-keywords (delq nil org-font-lock-extra-keywords)) ;; Now set the full font-lock-keywords @@ -2454,7 +2543,10 @@ between words." (inhibit-modification-hooks t) deactivate-mark buffer-file-name buffer-file-truename) (remove-text-properties beg end - '(mouse-face nil keymap nil org-linked-text nil)))) + '(mouse-face nil keymap nil org-linked-text nil + invisible nil intangible nil)))) +; intangible nil)))) +;;; FIXME: Is is a problem that we remove invisible here?????? ;;; Visibility cycling @@ -2712,6 +2804,7 @@ or nil." (insert-buffer-substring buf) (let ((org-startup-truncated t) (org-startup-folded t) + (org-startup-align-all-tables nil) (org-startup-with-deadline-check nil)) (org-mode)) (setq buffer-read-only t) @@ -5545,6 +5638,7 @@ the documentation of `org-diary'." (setq args (or args '(:deadline :scheduled :timestamp))) (let* ((org-startup-with-deadline-check nil) (org-startup-folded nil) + (org-startup-align-all-tables nil) (buffer (if (file-exists-p file) (org-get-agenda-file-buffer file) (error "No such file %s" file))) @@ -6474,7 +6568,6 @@ be used to request time specification in the time stamp." "Return the heading of the current entry, without the stars." (save-excursion (and (memq (char-before) '(?\n ?\r)) (skip-chars-forward "^\n\r")) -;;FIXME???????? (and (bolp) (end-of-line 1)) (if (and (re-search-backward "[\r\n]\\*" nil t) (looking-at "[\r\n]\\*+[ \t]+\\([^\r\n]*\\)")) (match-string 1) @@ -6933,7 +7026,7 @@ optional argument IN-EMACS is non-nil, Emacs will visit the file." (looking-at org-bracket-link-regexp) (<= (match-beginning 0) pos) (>= (match-end 0) pos)) - (setq link (match-string 1)) + (setq link (org-link-unescape (match-string 1))) (while (string-match " *\n *" link) (setq link (replace-match " " t t link))) (if (string-match org-link-regexp link) @@ -6980,6 +7073,8 @@ optional argument IN-EMACS is non-nil, Emacs will visit the file." (setq path (concat "*" path)))) (throw 'match t)) (save-excursion + ;; FIXME: This does not find bracket links, and maybe should be + ;; turned off totally, as the results are not very predictable. (when (re-search-forward org-link-regexp (save-excursion @@ -7553,7 +7648,7 @@ For some link types, a prefix arg is interpreted: For links to usenet articles, arg negates `org-usenet-links-prefer-google'. For file links, arg negates `org-context-in-file-links'." (interactive "P") - (let (link cpltxt txt (pos (point))) + (let (link cpltxt desc txt (pos (point))) (cond ((eq major-mode 'bbdb-mode) @@ -7589,9 +7684,7 @@ For file links, arg negates `org-context-in-file-links'." folder) (setq folder (replace-match "" t t folder))) (setq cpltxt (concat author " on: " subject)) - (setq link (concat cpltxt "\n " - (org-make-link - "vm:" folder "#" message-id)))))) + (setq link (org-make-link "vm:" folder "#" message-id))))) ((eq major-mode 'wl-summary-mode) (let* ((msgnum (wl-summary-message-number)) @@ -7603,10 +7696,8 @@ For file links, arg negates `org-context-in-file-links'." (subject "???")) ; FIXME: How to get subject of email? (setq message-id (org-remove-angle-brackets message-id)) (setq cpltxt (concat author " on: " subject)) - (setq link (concat cpltxt "\n " - (org-make-link - "wl:" wl-summary-buffer-folder-name - "#" message-id))))) + (setq link (org-make-link "wl:" wl-summary-buffer-folder-name + "#" message-id)))) ((or (equal major-mode 'mh-folder-mode) (equal major-mode 'mh-show-mode)) @@ -7614,11 +7705,9 @@ For file links, arg negates `org-context-in-file-links'." (to-header (org-mhe-get-header "To:")) (subject (org-mhe-get-header "Subject:"))) (setq cpltxt (concat from-header " on: " subject)) - (setq link (concat cpltxt "\n " - (org-make-link - "mhe:" (org-mhe-get-message-real-folder) "#" - (org-remove-angle-brackets - (org-mhe-get-header "Message-Id:"))))))) + (setq link (org-make-link "mhe:" (org-mhe-get-message-real-folder) "#" + (org-remove-angle-brackets + (org-mhe-get-header "Message-Id:")))))) ((eq major-mode 'rmail-mode) (save-excursion @@ -7630,9 +7719,7 @@ For file links, arg negates `org-context-in-file-links'." (subject (mail-fetch-field "subject"))) (setq message-id (org-remove-angle-brackets message-id)) (setq cpltxt (concat author " on: " subject)) - (setq link (concat cpltxt "\n " - (org-make-link - "rmail:" folder "#" message-id))))))) + (setq link (org-make-link "rmail:" folder "#" message-id)))))) ((eq major-mode 'gnus-group-mode) (let ((group (cond ((fboundp 'gnus-group-group-name) ; depending on Gnus @@ -7664,10 +7751,8 @@ For file links, arg negates `org-context-in-file-links'." cpltxt "\n " (format "http://groups.google.com/groups?as_umsgid=%s" (org-fixup-message-id-for-http message-id)))) - (setq link (concat cpltxt "\n" - (org-make-link - "gnus:" group - "#" (number-to-string article))))))) + (setq link (org-make-link "gnus:" group + "#" (number-to-string article)))))) ((eq major-mode 'w3-mode) (setq cpltxt (url-view-url t) @@ -7699,7 +7784,8 @@ For file links, arg negates `org-context-in-file-links'." (concat cpltxt "::" (if org-file-link-context-use-camel-case (org-make-org-heading-camel txt) - (org-make-org-heading-search-string txt)))))) + (org-make-org-heading-search-string txt))) + desc "NONE"))) (if (string-match "::\\'" cpltxt) (setq cpltxt (substring cpltxt 0 -2))) (setq link (org-make-link cpltxt))) @@ -7717,7 +7803,8 @@ For file links, arg negates `org-context-in-file-links'." (concat cpltxt "::" (if org-file-link-context-use-camel-case (org-make-org-heading-camel txt) - (org-make-org-heading-search-string txt))))) + (org-make-org-heading-search-string txt))) + desc "NONE")) (setq link (org-make-link cpltxt))) ((interactive-p) @@ -7726,13 +7813,16 @@ For file links, arg negates `org-context-in-file-links'." (t (setq link nil))) (if (consp link) (setq cpltxt (car link) link (cdr link))) + (setq link (or link cpltxt) + desc (or desc cpltxt)) + (if (equal desc "NONE") (setq desc nil)) (if (and (interactive-p) link) (progn (setq org-stored-links - (cons (cons (or cpltxt link) link) org-stored-links)) + (cons (list cpltxt link desc) org-stored-links)) (message "Stored: %s" (or cpltxt link))) - link))) + (org-make-link-string link desc)))) (defun org-make-org-heading-search-string (&optional string heading) "Make search string for STRING or current headline." @@ -7780,11 +7870,45 @@ For file links, arg negates `org-context-in-file-links'." "Concatenate STRINGS, format resulting string with `org-link-format'." (format org-link-format (apply 'concat strings))) -(defun org-make-link2 (link &optional description) - "Make a link with brackets." - (concat "[[" link "]" - (if description (concat "[" description "]") "") - "]")) +(defun org-make-link-string (link &optional description) + "Make a link with brackets, consisting of LINK and DESCRIPTION." + (if org-old-link-style + (concat description "\n" link) + (if (stringp description) + ;; Remove brackets from the description, they are fatal. + (while (string-match "\\[\\|\\]" description) + (setq description (replace-match "" t t description)))) + (concat "[[" (org-link-escape link) "]" + (if description (concat "[" description "]") "") + "]"))) + +;; FIXME: Do we need more characters here? +(defconst org-link-escape-chars '(("[" . "%5B") ("]" . "%5D") (" " . "%20")) + "Association list of escapes for some characters problematic in links.") + +(defun org-link-escape (text) + "Escape charaters in TEXT that are problematic for links." + (when text + (let ((re (mapconcat (lambda (x) (regexp-quote (car x))) + org-link-escape-chars "\\|"))) + (while (string-match re text) + (setq text + (replace-match + (cdr (assoc (match-string 0 text) org-link-escape-chars)) + t t text))) + text))) + +(defun org-link-unescape (text) + "Reverse the action of `org-link-escape'." + (when text + (let ((re (mapconcat (lambda (x) (regexp-quote (cdr x))) + org-link-escape-chars "\\|"))) + (while (string-match re text) + (setq text + (replace-match + (car (rassoc (match-string 0 text) org-link-escape-chars)) + t t text))) + text))) (defun org-xor (a b) "Exclusive or." @@ -7833,6 +7957,12 @@ press RET at the prompt), the link defaults to the most recently stored link. As SPC triggers completion in the minibuffer, you need to use M-SPC or C-q SPC to force the insertion of a space character. +You will also be prompted for a description, and if one is given, it will +be displayed in the buffer instead of the link. + +If there is already a link at point, this command will allow you to edit link +and description parts. + With a \\[universal-argument] prefix, prompts for a file to link to. The file name can be selected using completion. The path to the file will be relative to the current directory if the file is in the current directory or a @@ -7842,68 +7972,77 @@ completed in the minibuffer (i.e. normally ~/path/to/file). With two \\[universal-argument] prefixes, enforce an absolute path even if the file is in the current directory or below." (interactive "P") - (let ((link (if complete-file - (read-file-name "File: ") - (completing-read - "Link: " org-stored-links nil nil nil - org-insert-link-history - (or (car (car org-stored-links)))))) - linktxt matched) - (if (or (not link) (equal link "")) - (error "No links available")) - (if complete-file - (let ((pwd (file-name-as-directory (expand-file-name ".")))) - (cond - ((equal complete-file '(16)) - (insert - (org-make-link - "file:" (abbreviate-file-name (expand-file-name link))))) - ((string-match (concat "^" (regexp-quote pwd) "\\(.+\\)") - (expand-file-name link)) - (insert - (org-make-link - "file:" (match-string 1 (expand-file-name link))))) - (t (insert (org-make-link "file:" link))))) - (setq linktxt (cdr (assoc link org-stored-links))) + (let (link desc entry remove file (pos (point))) + (cond + ((save-excursion + (skip-chars-forward "^]\n\r") + (and (re-search-backward "\\[\\[" nil t) + (looking-at org-bracket-link-regexp) + (<= (match-beginning 0) pos) + (>= (match-end 0) pos))) + ;; We do have a link at point, and we are going to edit it. + (setq remove (list (match-beginning 0) (match-end 0))) + (setq desc (if (match-end 3) (match-string 3))) + (setq link (read-string "Link: " (org-match-string-no-properties 1)))) + (complete-file + ;; Completing read for file names. + (setq file (read-file-name "File: ")) + (let ((pwd (file-name-as-directory (expand-file-name ".")))) + (cond + ((equal complete-file '(16)) + (setq link (org-make-link + "file:" + (abbreviate-file-name (expand-file-name link))))) + ((string-match (concat "^" (regexp-quote pwd) "\\(.+\\)") + (expand-file-name link)) + (setq link (org-make-link + "file:" (match-string 1 (expand-file-name link))))) + (t (setq link (org-make-link "file:" link)))))) + (t + ;; Read link, with completion for stored links. + (setq link (completing-read + "Link: " org-stored-links nil nil nil + org-insert-link-history + (or (car (car org-stored-links))))) + (setq entry (assoc link org-stored-links)) (if (not org-keep-stored-link-after-insertion) (setq org-stored-links (delq (assoc link org-stored-links) org-stored-links))) - (if (not linktxt) (setq link (org-make-link link))) - (setq link (or linktxt link)) - (when (string-match "<\\]+\\)>" link) - (let* ((path (match-string 1 link)) - (case-fold-search nil) - (search (match-string 2 link))) - (when (save-match-data - (equal (file-truename buffer-file-name) - (file-truename path))) - ;; We are linking to this same file - (if (and org-file-link-context-use-camel-case - (save-match-data - (string-match (concat "^" org-camel-regexp "$") search))) - (setq link (replace-match search t t link) - matched t) - (setq link (replace-match (concat "[[" search "]]") - t t link) - matched t))))) - (let ((lines (org-split-string link "\n"))) - (insert (car lines)) - (setq matched (or matched (string-match org-link-regexp (car lines)))) - (setq lines (cdr lines)) - (while lines - (insert "\n") - (if (save-excursion - (beginning-of-line 0) - (looking-at "[ \t]+\\S-")) - (indent-relative)) - (setq matched (or matched - (string-match org-link-regexp (car lines)))) - (insert (car lines)) - (setq lines (cdr lines)))) - (unless matched - (error "Add link type: http(s),ftp,mailto,file,news,bbdb,vm,wl,rmail,gnus, or shell"))))) + (setq link (if entry (nth 1 entry) link) + desc (or desc (nth 2 entry))))) + + (if (string-match org-link-regexp link) + ;; URL-like link, normalize the use of angular brackets. + (setq link (org-make-link (org-remove-angle-brackets link)))) + + ;; Check if we are linking to the current file. If yes, simplify the link. + (when (string-match "\\]+\\)" link) + (let* ((path (match-string 1 link)) + (case-fold-search nil) + (search (match-string 2 link))) + (when (save-match-data + (equal (file-truename buffer-file-name) + (file-truename path))) + ;; We are linking to this same file, with a search option + (setq link search)))) +; FIXME: Do we need to re-enable camel case????? I prefer not... +; (if (and org-file-link-context-use-camel-case +; (save-match-data +; (string-match (concat "^" org-camel-regexp "$") search))) +; (setq link (replace-match search t t link) +; matched t) +; (setq link (replace-match (concat "[[" search "]]") +; t t link) +; matched t))))) + (setq desc (read-string "Description: " desc)) + (unless (string-match "\\S-" desc) (setq desc nil)) + (if remove (apply 'delete-region remove)) + (insert (org-make-link-string link desc)))) ;;; Hooks for remember.el + +(defvar org-finish-function nil) + ;;;###autoload (defun org-remember-annotation () "Return a link to the current location as an annotation for remember.el. @@ -7928,7 +8067,7 @@ to be run from that hook to fucntion properly." (let* ((entry (if (= (length org-remember-templates) 1) (cdar org-remember-templates) (message "Select template: %s" - (mapconcat + (mapconcat (lambda (x) (char-to-string (car x))) org-remember-templates " ")) (cdr (assoc (read-char-exclusive) org-remember-templates)))) @@ -7952,18 +8091,17 @@ to be run from that hook to fucntion properly." (setq v-i (mapconcat 'identity (org-split-string initial "\n") (concat "\n" lead)))))) - (replace-match + (replace-match (or (eval (intern (concat "v-" (match-string 1)))) "") t t)) (let ((org-startup-folded nil) (org-startup-with-deadline-check nil)) (org-mode)) -; (use-local-map org-mode-map) -; (org-set-font-lock-defaults) (if (and file (string-match "\\S-" file) (not (file-directory-p file))) (set (make-local-variable 'org-default-notes-file) file)) (goto-char (point-min)) - (if (re-search-forward "%\\?" nil t) (replace-match ""))))) + (if (re-search-forward "%\\?" nil t) (replace-match "")) + (set (make-local-variable 'org-finish-function) 'remember-buffer)))) ;;;###autoload (defun org-remember-handler () @@ -8006,6 +8144,7 @@ See also the variable `org-reverse-note-order'." (visiting (find-buffer-visiting file)) (org-startup-with-deadline-check nil) (org-startup-folded nil) + (org-startup-align-all-tables nil) spos level indent reversed) ;; Modify text so that it becomes a nice subtree which can be inserted ;; into an org tree. @@ -8272,7 +8411,6 @@ This is being used to correctly align a single field after TAB or RET.") (defun org-table-align () "Align the table at point by aligning all vertical bars." (interactive) - ;; (message "align") (sit-for 2) (let* ( ;; Limits of table (beg (org-table-begin)) @@ -8294,16 +8432,26 @@ This is being used to correctly align a single field after TAB or RET.") (make-string sp2 ?\ ) "%%%s%ds" (make-string sp1 ?\ ) "|")) (hfmt1 (concat (make-string sp2 ?-) "%s" (make-string sp1 ?-) "+")) - emptystrings) + emptystrings xx links narrow fmax fmin f1 len c e) (untabify beg end) - ;; (message "Aligning table...") + (remove-text-properties beg end '(org-cwidth t display t)) + ;; Check if we have links + (goto-char beg) + (setq links (re-search-forward org-bracket-link-regexp end t)) + ;; Make sure the link properties are right FIXME: Can this be optimized???? + (when links (goto-char beg) (while (org-activate-links2 end))) + ;; Check if we are narrowing any columns + (goto-char beg) + (setq narrow (and org-format-transports-properties-p + (re-search-forward "<[0-9]+>" end t))) ;; Get the rows (setq lines (org-split-string - (buffer-substring-no-properties beg end) "\n")) + (buffer-substring beg end) "\n")) ;; Store the indentation of the first line (if (string-match "^ *" (car lines)) (setq indent (make-string (- (match-end 0) (match-beginning 0)) ?\ ))) - ;; Mark the hlines + ;; Mark the hlines by setting the corresponding element to nil + ;; At the same time, we remove trailing space. (setq lines (mapcar (lambda (l) (if (string-match "^ *|-" l) nil @@ -8311,7 +8459,7 @@ This is being used to correctly align a single field after TAB or RET.") (substring l 0 (match-beginning 0)) l))) lines)) - ;; Get the data fields + ;; Get the data fields by splitting the lines. (setq fields (mapcar (lambda (l) (org-split-string l " *| *")) @@ -8325,28 +8473,63 @@ This is being used to correctly align a single field after TAB or RET.") (error "Empty table - created default table"))) ;; A list of empty string to fill any short rows on output (setq emptystrings (make-list maxfields "")) - ;; Get the maximum length of a field and the most common datatype - ;; for each column + ;; Check for special formatting. (setq i -1) (while (< (setq i (1+ i)) maxfields) ;; Loop over all columns (setq column (mapcar (lambda (x) (or (nth i x) "")) fields)) - ;; maximum length - (push (apply 'max 1 (mapcar 'string-width column)) lengths) - ;; compute the fraction stepwise, ignoring empty fields + ;; Check if there is an explicit width specified + (when (and org-table-limit-column-width narrow) + (setq c column fmax nil) + (while c + (setq e (pop c)) + (if (and (stringp e) (string-match "^<\\([0-9]+\\)>$" e)) + (setq fmax (string-to-number (match-string 1 e)) c nil))) + ;; Find fields that are wider than fmax, and shorten them + (when fmax + (loop for xx in column do + (when (and (stringp xx) + (> (org-string-width xx) fmax)) + (add-text-properties + 0 (length xx) + (list 'help-echo + (concat "Clipped table field, use C-c ` to edit. Full value is:\n" + (copy-sequence xx))) + xx) + (setq f1 (min fmax (or (string-match org-bracket-link-regexp xx) fmax))) + (unless (> f1 1) + (error "Cannot narrow field starting with wide link \"%s\"" + (match-string 0 xx))) + (add-text-properties f1 (length xx) (list 'org-cwidth t) xx) + (add-text-properties (- f1 2) f1 (list 'display "=>") xx))))) + ;; Get the maximum width for each column + (push (apply 'max 1 (mapcar 'org-string-width column)) lengths) + ;; Get the fraction of numbers, to decide about alignment of the column (setq cnt 0 frac 0.0) - (mapcar - (lambda (x) - (if (equal x "") - nil - (setq frac ( / (+ (* frac cnt) - (if (string-match org-table-number-regexp x) 1 0)) - (setq cnt (1+ cnt)))))) - column) + (loop for x in column do + (if (equal x "") + nil + (setq frac ( / (+ (* frac cnt) + (if (string-match org-table-number-regexp x) 1 0)) + (setq cnt (1+ cnt)))))) (push (>= frac org-table-number-fraction) typenums)) - (setq lengths (nreverse lengths) - typenums (nreverse typenums)) + (setq lengths (nreverse lengths) typenums (nreverse typenums)) + + ;; Store the alignment of this table, for later editing of single fields (setq org-table-last-alignment typenums org-table-last-column-widths lengths) + + ;; With invisible characters, `format' does not get the field width right + ;; So we need to make these fields wide by hand. + (when links + (loop for i from 0 upto (1- maxfields) do + (setq len (nth i lengths)) + (loop for j from 0 upto (1- (length fields)) do + (setq c (nthcdr i (car (nthcdr j fields)))) + (if (and (stringp (car c)) + (string-match org-bracket-link-regexp (car c)) + (< (org-string-width (car c)) len)) + (setcar c (concat (car c) (make-string (- len (org-string-width (car c))) ?\ ))))))) + ;; Compute the formats needed for output of the table (setq rfmt (concat indent "|") hfmt (concat indent "|")) (while (setq l (pop lengths)) @@ -8355,13 +8538,7 @@ This is being used to correctly align a single field after TAB or RET.") hfmt (concat hfmt (format hfmt1 (make-string l ?-))))) (setq rfmt (concat rfmt "\n") hfmt (concat (substring hfmt 0 -1) "|\n")) - ;; Produce the new table - ;;(while lines - ;; (setq l (pop lines)) - ;; (if l - ;; (setq new (concat new (apply 'format rfmt - ;; (append (pop fields) emptystrings)))) - ;; (setq new (concat new hfmt)))) + (setq new (mapconcat (lambda (l) (if l (apply 'format rfmt @@ -8383,6 +8560,20 @@ This is being used to correctly align a single field after TAB or RET.") (org-table-add-invisible-to-vertical-lines)) )) +(defun org-string-width (s) + "Compute width of string, ignoring invisible characters. +This ignores character with invisibility property `org-link', and also +characters with property `org-cwidth', because these will become invisible +upon the next fontification round." + (let (b) + (when (or (eq t buffer-invisibility-spec) + (assq 'org-link buffer-invisibility-spec)) + (while (setq b (text-property-any 0 (length s) 'invisible 'org-link s)) + (setq s (concat (substring s 0 b) (substring s (or (next-single-property-change b 'invisible s) (length s))))))) + (while (setq b (text-property-any 0 (length s) 'org-cwidth t s)) + (setq s (concat (substring s 0 b) (substring s (or (next-single-property-change b 'org-cwidth s) (length s)))))) + (string-width s))) + (defun org-table-begin (&optional table-type) "Find the beginning of the table and return its position. With argument TABLE-TYPE, go to the beginning of a table.el-type table." @@ -8587,7 +8778,7 @@ This actually throws an error, so it aborts the current command." (if (looking-at "|[^|\n]+") (let* ((pos (match-beginning 0)) (match (match-string 0)) - (len (string-width match))) + (len (org-string-width match))) (replace-match (concat "|" (make-string (1- len) ?\ ))) (goto-char (+ 2 pos)) (substring match 1))))) @@ -9134,6 +9325,51 @@ blank, and the content is appended to the field above." (insert (org-trim s) " ") (org-table-align)))))) +(defvar org-field-marker nil) + +;; FIXME: Put documentation into the editing buffer. +(defun org-table-edit-field () + "Edit table field in a different buffer. +Mainly useful for fields that contain hidden parts." + (interactive) + (let ((pos (move-marker (make-marker) (point))) + (field (org-table-get-field)) + (cw (current-window-configuration))) + (switch-to-buffer-other-window "*Org tmp*") + (erase-buffer) + (org-mode) + (insert (org-trim field)) + (remove-text-properties (point-min) (point-max) + '(invisible t org-cwidth t display t)) + (goto-char (point-min)) + (set (make-local-variable 'org-finish-function) + 'org-table-finish-edit-field) + (set (make-local-variable 'org-window-configuration) cw) + (set (make-local-variable 'org-field-marker) pos) + (message "Edit and finish with C-c C-c"))) + +(defun org-table-finish-edit-field () + "Finish editing a table data field. +Remove all newline characters, insert the result into the table, realign +the table and kill the editing buffer." + (let ((pos org-field-marker) + (cw org-window-configuration) + (cb (current-buffer)) + text) + (goto-char (point-min)) + (while (re-search-forward "[ \t]*\n[ \t]*" nil t) + (replace-match " ")) + (setq text (org-trim (buffer-string))) + (set-window-configuration cw) + (kill-buffer cb) + (select-window (get-buffer-window (marker-buffer pos))) + (goto-char pos) + (move-marker pos nil) + (org-table-check-inside-data-field) + (org-table-get-field nil text) + (org-table-align) + (message "New field value inserted"))) + (defun org-trim (s) "Remove whitespace at beginning and end of string." (if (string-match "^[ \t]+" s) (setq s (replace-match "" t t s))) @@ -9149,7 +9385,7 @@ IF WIDTH is nil and LINES is non-nil, the string is forced into at most that many lines, whatever width that takes. The return value is a list of lines, without newlines at the end." (let* ((words (org-split-string string "[ \t\n]+")) - (maxword (apply 'max (mapcar 'string-width words))) + (maxword (apply 'max (mapcar 'org-string-width words))) w ll) (cond (width (org-do-wrap words (max maxword width))) @@ -9259,7 +9495,8 @@ visible when ARG is not positive." (beginning-of-line 1) (if (looking-at org-table-line-regexp) (save-excursion (funcall function))) - (re-search-forward org-table-any-border-regexp nil 1))))) + (re-search-forward org-table-any-border-regexp nil 1)))) + (message "Mapping tables: done")) (defun org-table-sum (&optional beg end nlast) "Sum numbers in region of current table column. @@ -10223,6 +10460,7 @@ to execute outside of tables." '("\C-c|" org-table-toggle-vline-visibility) '("\C-c=" org-table-eval-formula) '("\C-c'" org-table-edit-formulas) + '("\C-c`" org-table-edit-field) '("\C-c*" org-table-recalculate) '("\C-c^" org-table-sort-lines) '([(control ?#)] org-table-rotate-recalc-marks))) @@ -10262,6 +10500,7 @@ to execute outside of tables." ["Next Row" org-return :active (org-at-table-p) :keys "RET"] "--" ["Blank Field" org-table-blank-field :active (org-at-table-p) :keys "C-c SPC"] + ["Edit Field" org-table-edit-field :active (org-at-table-p) :keys "C-c ` "] ["Copy Field from Above" org-table-copy-down :active (org-at-table-p) :keys "S-RET"] "--" @@ -10269,7 +10508,9 @@ to execute outside of tables." ["Move Column Left" org-metaleft :active (org-at-table-p) :keys "M-"] ["Move Column Right" org-metaright :active (org-at-table-p) :keys "M-"] ["Delete Column" org-shiftmetaleft :active (org-at-table-p) :keys "M-S-"] - ["Insert Column" org-shiftmetaright :active (org-at-table-p) :keys "M-S-"]) + ["Insert Column" org-shiftmetaright :active (org-at-table-p) :keys "M-S-"] + "--" + ["Enable Narrowing" (setq org-table-limit-column-width (not org-table-limit-column-width)) :active (org-at-table-p) :selected org-table-limit-column-width :style toggle]) ("Row" ["Move Row Up" org-metaup :active (org-at-table-p) :keys "M-"] ["Move Row Down" org-metadown :active (org-at-table-p) :keys "M-"] @@ -11047,7 +11288,7 @@ Does include HTML export options as well as TODO and CATEGORY stuff." #+CATEGORY: %s #+SEQ_TODO: %s #+TYP_TODO: %s -#+STARTUP: %s %s %s %s +#+STARTUP: %s %s %s %s %s #+ARCHIVE: %s " (buffer-name) (user-full-name) user-mail-address org-export-default-language @@ -11073,6 +11314,7 @@ Does include HTML export options as well as TODO and CATEGORY stuff." (if org-startup-with-deadline-check "dlcheck" "nodlcheck") (if org-odd-levels-only "odd" "oddeven") (if org-hide-leading-stars "hidestars" "showstars") + (if org-startup-align-all-tables "align" "noalign") org-archive-location )) @@ -11351,7 +11593,7 @@ headlines. The default is 3. Lower levels will become bulleted lists." (cond ((match-end 2) (setq line (replace-match - (concat "@\\nbsp@") t t line))) @@ -11362,10 +11604,10 @@ headlines. The default is 3. Lower levels will become bulleted lists." t t line))) (t (setq line (replace-match - (concat "@" (match-string 1 line) "@ ") - t t line))))) + t t line))))) ;; Replace internal links (while (string-match org-bracket-link-regexp line) (setq line (replace-match @@ -11769,7 +12011,7 @@ stacked delimiters is N. Escaping delimiters is not possible." (setq c (cdr (assoc (match-string 2 string) '(("*" . "b") ("/" . "i") ("_" . "u")))) s (+ (match-end 0) 3) - string (replace-match + string (replace-match (concat "\\1<" c ">\\3\\4") t nil string))) string)) @@ -12021,6 +12263,7 @@ END:VTODO\n" (name (or name "unknown")) (timezone (cadr (current-time-zone)))) (princ + ;; FIXME: Should we use VERSION 1? MS Outlook would then work, it seems (format "BEGIN:VCALENDAR VERSION:2.0 X-WR-CALNAME:%s @@ -12150,6 +12393,7 @@ a time), or the day by one (if it does not contain a time)." (define-key org-mode-map "\C-c|" 'org-table-toggle-vline-visibility) (define-key org-mode-map "\C-c=" 'org-table-eval-formula) (define-key org-mode-map "\C-c'" 'org-table-edit-formulas) +(define-key org-mode-map "\C-c`" 'org-table-edit-field) (define-key org-mode-map "\C-c*" 'org-table-recalculate) (define-key org-mode-map [(control ?#)] 'org-table-rotate-recalc-marks) (define-key org-mode-map "\C-c~" 'org-table-create-with-table.el) @@ -12443,8 +12687,11 @@ If the cursor is on a #+TBLFM line, re-apply the formulae to the table." (interactive "P") (let ((org-enable-table-editor t)) (cond - ((and (boundp 'remember-buffer) (equal (buffer-name) remember-buffer)) - (remember-buffer)) + ((and (local-variable-p 'org-finish-function (current-buffer)) + (fboundp org-finish-function)) + (funcall org-finish-function)) +; ((and (boundp 'remember-buffer) (equal (buffer-name) remember-buffer)) +; (remember-buffer)) ;; FIXME: remove this?????? ((org-on-target-p) (org-update-radio-target-regexp)) ((org-on-heading-p) (org-set-tags arg)) ((org-at-table.el-p) @@ -12519,13 +12766,16 @@ See the individual commands for more information." ["Next Row" org-return (org-at-table-p)] "--" ["Blank Field" org-table-blank-field (org-at-table-p)] + ["Edit Field" org-table-edit-field (org-at-table-p)] ["Copy Field from Above" org-table-copy-down (org-at-table-p)] "--" ("Column" ["Move Column Left" org-metaleft (org-at-table-p)] ["Move Column Right" org-metaright (org-at-table-p)] ["Delete Column" org-shiftmetaleft (org-at-table-p)] - ["Insert Column" org-shiftmetaright (org-at-table-p)]) + ["Insert Column" org-shiftmetaright (org-at-table-p)] + "--" + ["Enable Narrowing" (setq org-table-limit-column-width (not org-table-limit-column-width)) :active (org-at-table-p) :selected org-table-limit-column-width :style toggle]) ("Row" ["Move Row Up" org-metaup (org-at-table-p)] ["Move Row Down" org-metadown (org-at-table-p)] @@ -12635,7 +12885,16 @@ See the individual commands for more information." ("Hyperlinks" ["Store Link (Global)" org-store-link t] ["Insert Link" org-insert-link t] - ["Follow Link" org-open-at-point t]) + ["Follow Link" org-open-at-point t] + "--" + ["Descriptive Links" + (progn (org-add-to-invisibility-spec '(org-link)) (org-restart-font-lock)) + :style radio :selected (member '(org-link) buffer-invisibility-spec)] + ["Literal Links" + (progn + (org-remove-from-invisibility-spec '(org-link)) (org-restart-font-lock)) + :style radio :selected (not (member '(org-link) buffer-invisibility-spec))] + ) "--" ("Export" ["ASCII" org-export-as-ascii t] @@ -12943,10 +13202,10 @@ If INVISIBLE-OK is non-nil, an invisible heading line is ok too." (save-excursion (skip-chars-forward "<") (and (re-search-backward "<<" nil t) - (or (looking-at org-target-regexp) - (looking-at org-radio-target-regexp)) + (or (looking-at org-radio-target-regexp) + (looking-at org-target-regexp)) (<= (match-beginning 0) pos) - (>= (match-end 0) pos))))) + (>= (1+ (match-end 0)) pos))))) (defun org-up-heading-all (arg) "Move to the heading line of which the present line is a subheading. @@ -13084,7 +13343,6 @@ Show the heading too, if it is currently invisible." ;; Experimental code - ;; arch-tag: e77da1a7-acc7-4336-b19e-efa25af3f9fd ;;; org.el ends here diff --git a/org.pdf b/org.pdf index c45f195d2..bd0ce2379 100644 Binary files a/org.pdf and b/org.pdf differ diff --git a/org.texi b/org.texi index 8e21e8c51..b136bb4ff 100644 --- a/org.texi +++ b/org.texi @@ -4,7 +4,7 @@ @c @setfilename ../info/org @settitle Org Mode Manual -@set VERSION 4.13 +@set VERSION 4.19a @set DATE March 2006 @dircategory Emacs @@ -82,6 +82,7 @@ Software Foundation raise funds for GNU development.'' * 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 * Exporting:: Sharing and publishing of notes * Miscellaneous:: All the rest which did not fit elsewhere @@ -106,12 +107,12 @@ 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 -* Tags:: Tagging headlines and matching sets of tags * Plain Lists:: Editing hand-formatted lists Tables * Built-in table editor:: Simple tables +* Narrow columns:: Stop wasting space in tables * Table calculations:: Compute a field from other fields * orgtbl-mode:: The table editor as minor mode * table.el:: Complex tables @@ -127,6 +128,7 @@ Calculations in tables 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 @@ -156,6 +158,12 @@ Timestamps * Time stamps:: Assigning a time to a tree entry * Creating timestamps:: Commands which insert timestamps +Tags + +* Tag inheritance:: Tags use the tree structure of the outline +* Setting tags:: How to assign tags to a headline +* Tag searches:: Searching for combinations of tags + Agenda Views * Agenda files:: Files being searched for agenda information @@ -343,7 +351,6 @@ 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 -* Tags:: Tagging headlines and matching sets of tags * Plain Lists:: Editing hand-formatted lists @end menu @@ -567,7 +574,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, Tags, Archiving, Document Structure +@node Sparse trees, Plain Lists, Archiving, Document Structure @section Sparse trees @cindex sparse trees @cindex trees, sparse @@ -624,85 +631,8 @@ 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 Tags, Plain Lists, Sparse trees, Document Structure -@section Tags -@cindex tags -@cindex headline tagging -@cindex matching, tags -@cindex sparse tree, tag based -If you wish to implement a tag system to cross-correlate information, -this can be done as well in Org-mode. Every headline can contain a -list of tags, at the end of the headline. Tags are normal words -containing letters, numbers, @samp{_}, and @samp{@@}. Tags must be -preceded and followed by a single colon; like @samp{:WORK:}. Several -tags can be specified like @samp{:WORK:URGENT:}. - -@cindex inheritance, of tags -Tags make use of the hierarchical structure of outline trees. If a -heading has a certain tag, all subheadings will inherit the tag as -well. For example, in the list - -@example -* Meeting with the French group :WORK: -** Summary by Frank :BOSS:NOTES: -*** TODO Prepare slides for him :ACTION: -@end example -@noindent -the final heading will have the tags @samp{:WORK:}, @samp{:BOSS:}, -@samp{:NOTES:}, and @samp{:ACTION:}. When executing tag searches and -Org-mode finds that a certain headline matches the search criterion, -it will not check any sublevel headline, assuming that these likely -also match, and that the list of matches can become very long. You -can influence inheritance and searching using the variables -@code{org-use-tag-inheritance} and -@code{org-tags-match-list-sublevels}. - -@kindex M-@key{TAB} -Tags can simply be typed into the buffer. After a colon, -@kbd{M-@key{TAB}} offers completion on all tags being used in the -current buffer. There are also special commands for inserting tags, -and for executing searches based on tags. - -@table @kbd -@kindex C-c C-c -@item C-c C-c -@cindex completion, of tags -Enter new tags for the current headline. The minibuffer will prompt -for a list of tags and offer completion with respect to all other tags -used in the current buffer. Several tags, separated by colons, may be -specified at the prompt. After pressing @key{RET}, the tags will -be inserted and aligned to @code{org-tags-column}. When called with a -@kbd{C-u} prefix, align all tags in the current buffer to that column, -just to make things look nice. TAGS are automatically realigned after -promotion, demotion, and TODO state changes (@pxref{TODO basics}). -@kindex C-c \ -@item C-c \ -Create a sparse tree with all headlines matching a tags search. -@kindex C-c a m -@item C-c a m -Create a global list of tag matches from all agenda files. -@xref{Matching headline tags}. -@kindex C-c a M -@item C-c a M -Create a global list of tag matches from all agenda files, but check -only TODO items and force checking subitems (see variable -@code{org-tags-match-list-sublevels}). -@end table - -A tags search string can use Boolean operators @samp{&} for AND and -@samp{|} for OR. @samp{&} binds more strongly than -@samp{|}. Parenthesis are currently not implemented. A tag may also be -preceded by @samp{-}, to select against it, and @samp{+} is syntactic -sugar for positive selection. The AND operator @samp{&} is optional -when @samp{+} or @samp{-} is present. For example, @samp{+WORK-BOSS} -would select all headlines that are tagged @samp{:WORK:}, but discard -those also tagged @samp{:BOSS:}. The search string @samp{WORK|LAPTOP} -selects all lines tagged @samp{:WORK:} or @samp{:LAPTOP:}. The string -@samp{WORK|LAPTOP&NIGHT} requires that the @samp{:LAPTOP:} lines are -also tagged @samp{NIGHT}. - -@node Plain Lists, , Tags, Document Structure +@node Plain Lists, , Sparse trees, Document Structure @section Plain Lists @cindex plain lists @cindex lists, plain @@ -792,12 +722,13 @@ Emacs @file{calc} package. @menu * Built-in table editor:: Simple tables +* Narrow columns:: Stop wasting space in tables * Table calculations:: Compute a field from other fields * orgtbl-mode:: The table editor as minor mode * table.el:: Complex tables @end menu -@node Built-in table editor, Table calculations, Tables, Tables +@node Built-in table editor, Narrow columns, Tables, Tables @section The built-in table editor @cindex table editor, builtin @@ -1000,6 +931,11 @@ incremented during copy. This key is also used by CUA-mode (@pxref{Interaction}). @tsubheading{Miscellaneous} +@kindex C-c ` +@item C-c ` +Edit the current field in a separate window. This is useful for fields +that are not fully visible (@pxref{Narrow columns}). + @kindex C-c | @item C-c | Toggle the visibility of vertical lines in tables. The lines are @@ -1029,7 +965,48 @@ it off with @noindent The only table command which then still works is @kbd{C-c C-c} to do a manual re-align. -@node Table calculations, orgtbl-mode, Built-in table editor, Tables +@node Narrow columns, Table calculations, Built-in table editor, Tables +@section Narrow columns +@cindex narrow columns in tables + +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 unconveniently 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. + +@example +|---+------------------------------| |---+--------| +| | | | | <6> | +| 1 | one | | 1 | one | +| 2 | two | ----\ | 2 | two | +| 3 | This is a long chunk of text | ----/ | 3 | This=> | +| 4 | four | | 4 | four | +|---+------------------------------| |---+--------| +@end example +@noindent +Fields that are wider become clipped and end in the string @samp{=>}. +Note that the full text is still in the buffer, it is only invisible. +To see the full text, hold the mouse over the field - a tooltip window +will show the full content. To edit such a field, use the command +@kbd{C-c `} (that is @kbd{C-c} followed by the backquote). This will +open a new window with the full field. Edit it and finish with @kbd{C-c +C-c}. + +When visiting a file containing a table with narrowed columns, the +necessary character hiding has not yet happened, and the table needs to +be aligned before it looks nice. Setting the option +@code{org-startup-align-all-tables} will realign all tables in a file +upon visiting, but also slow down startup. You can also set this option +on a per-file basis with: +@example +#+STARTUP: align +#+STARTUP: noalign +@end example + +@node Table calculations, orgtbl-mode, Narrow columns, Tables @section Calculations in tables @cindex calculations, in tables @cindex spreadsheet capabilities @@ -1362,6 +1339,7 @@ Just like HMTL, Org-mode provides links inside a file, and external links to other files, Usenet articles, emails and much more. @menu +* 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 @@ -1369,39 +1347,65 @@ links to other files, Usenet articles, emails and much more. * Remember:: Org-trees store quick notes @end menu -@node Internal links, External links, Hyperlinks, Hyperlinks +@node Link format, Internal links, Hyperlinks, Hyperlinks +@section Link format +@cindex link format +@cindex format, of links + +Org-mode will recognize plain URL-like links in the buffer and activate +them as clickable links. However, the general linkformat in Org-mode +looks like: +@example +[[link][description]] @r{or alternatively} [[link]] +@end example +The description part is optional. Once a link in the buffer is +complete, Org-mode will change the display so that +@u{@samp{description}} is displayed instead of +@samp{[[link][description]]} and @samp{link} is displayed instead of +@samp{[[link]]}. Links will be highlighted in the face @code{org-link}, +which by default is an underlined face. You can directly edit the +visible part of a link. To edit the invisible part, use @kbd{C-c C-l} +with the cursor on the link@footnote{You can also position the cursor +directly after the link and press @key{BACKSPACE} to remove the +(invisible) closing bracket @samp{]}. This makes the link incomplete, +and shows the full raw link text for you to edit. You may also use the +menu entry @code{Org->Hperlinks->Literal links} to unhide all links.}. + +@node Internal links, External links, Link format, Hyperlinks @section Internal links @cindex internal links @cindex links, internal @cindex CamelCase links -Strings inside double brackets like @samp{[[My Target]]} are links -that lead to a text search in the current file. The link can be -followed with @kbd{C-c C-o} 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 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 @example # <> @end example -If no dedicated target exists, Org-mode will search for the words in -the link, in the above example 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: +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: @example ** My targets ** TODO my targets are bright ** my 20 targets are @end example -It is therefore often not necessary to set a dedicated target. 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 + +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 creating links. Following a link pushes a mark onto Org-mode's own mark ring. You can @@ -1460,8 +1464,8 @@ needed: @cindex SHELL links Org-mode supports links to files, websites, Usenet and email messages; -and BBDB database entries. Links are just plain-text URL-like -locators, optionally enclosed by angular brackets. The following list +and BBDB database entries. External links are plain-text URL-like +locators, optionally enclosed in angular brackets. The following list shows examples for each link type. @example @@ -1489,7 +1493,15 @@ A link may contain space characters and is terminated by @samp{>} or by the end of a line. In tables, the end of a table field also terminates a link. Angle brackets around a link are not required, but are recommended to avoid problems with punctuation and other text following -the link. See also the variable @code{org-allow-space-in-links}. +the link. + +To display a descriptive text instead of the URL, enclose the link into +double brackets and add the descriptive text like this: +@example +[[][GNU Emacs]] +@end example +@noindent Links inserted with @kbd{C-c C-l} automatically use the double +bracket format (@pxref{Managing links}). @node Managing links, Search Options, External links, Hyperlinks @@ -1522,15 +1534,16 @@ activation}. @cindex completion, of file names @cindex inserting links @item 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 one of the link type prefixes -mentioned in the examples above. Through completion, all links stored -during the current session can be accessed. When called with prefix -arg, you can use file name completion to enter a file link. The link -will be formatted as given in the variable @code{org-link-format} and -inserted into the buffer. 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. +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. When +called with prefix arg, you can use file name completion to enter a file +link. 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. @cindex following links @kindex C-c C-o @@ -1538,7 +1551,7 @@ can type or paste them straight into the buffer. Open link at point. This will launch a web browser for URLs (using @command{browse-url-at-point}), run vm/gnus/bbdb for the corresponding links, and execute the command in a shell link. When the cursor is on -a CamelCase link, this commands runs the corresponding search. When +am internal link, this commands runs the corresponding search. When the cursor is on a TAGS list in a headline, it creates the corresponding TAGS view. Furthermore, it will visit text files in @samp{file:} links with Emacs and select a suitable application for @@ -1803,12 +1816,14 @@ each day, giving you an overview of what has been done on a day. @section Extended use of TODO keywords @cindex extended TODO keywords -The default implementation of TODO entries is just two states: TODO -and DONE. You can, however, use the TODO feature for more -complicated things by configuring the variables -@code{org-todo-keywords} and @code{org-todo-interpretation}. Using -special setup, you can even use TODO keywords in different ways in -different org files. +The default implementation of TODO entries is just two states: TODO and +DONE. You can, however, use the TODO feature for more complicated +things by configuring the variables @code{org-todo-keywords} and +@code{org-todo-interpretation}. Using special setup, you can even use +TODO keywords in different ways in different org files. + +Note that @i{tags} are another way to classify headlines in general and +TODO items in particular (@pxref{Tags}). @menu * Workflow states:: From TODO to DONE in steps @@ -1956,7 +1971,7 @@ Furthermore, these keys are also used by CUA-mode (@pxref{Interaction}). @end table -@node Timestamps, Agenda Views, TODO items, Top +@node Timestamps, Tags, TODO items, Top @chapter Timestamps Items can be labeled with timestamps to make them useful for project @@ -2153,15 +2168,118 @@ One month back. Choose date in calendar (only if nothing typed into minibuffer). @end table -@node Agenda Views, Exporting, Timestamps, Top +@node Tags, Agenda Views, Timestamps, Top +@chapter Tags +@cindex tags +@cindex headline tagging +@cindex matching, tags +@cindex sparse tree, tag based + +If you wish to implement a system to cross-correlate information, an +excellent ways is assigning @i{tags} to headline. Org-mode has +extensive support for using tags. + +Every headline can contain a list of tags, at the end of the headline. +Tags are normal words containing letters, numbers, @samp{_}, and +@samp{@@}. Tags must be preceded and followed by a single colon; like +@samp{:WORK:}. Several tags can be specified like @samp{:WORK:URGENT:}. + +@menu +* Tag inheritance:: Tags use the tree structure of the outline +* Setting tags:: How to assign tags to a headline +* Tag searches:: Searching for combinations of tags +@end menu + +@node Tag inheritance, Setting tags, Tags, Tags +@section Tag inheritance +@cindex inheritance, of tags + +@i{Tags} make use of the hierarchical structure of outline trees. If a +heading has a certain tag, all subheadings will inherit the tag as +well. For example, in the list + +@example +* Meeting with the French group :WORK: +** Summary by Frank :BOSS:NOTES: +*** TODO Prepare slides for him :ACTION: +@end example +@noindent +the final heading will have the tags @samp{:WORK:}, @samp{:BOSS:}, +@samp{:NOTES:}, and @samp{:ACTION:}. When executing tag searches and +Org-mode finds that a certain headline matches the search criterion, it +will not check any sublevel headline, assuming that these likely also +match, and that the list of matches can become very long. However, this +may not be what you want, and you can influence inheritance and +searching using the variables @code{org-use-tag-inheritance} and +@code{org-tags-match-list-sublevels}. + +@node Setting tags, Tag searches, Tag inheritance, Tags +@section Setting tags +@cindex setting tags + +@kindex M-@key{TAB} +As Org-mode deals with plain text files, tags can simply be typed into +the buffer. After a colon, @kbd{M-@key{TAB}} offers completion on all +tags being used in the current buffer. There is also a special command +for inserting tags: + +@table @kbd +@kindex C-c C-c +@item C-c C-c +@cindex completion, of tags +Enter new tags for the current headline. The minibuffer will prompt for +a list of tags and offer completion with respect to all other tags used +in the current buffer. Several tags, separated by colons, may be +specified at the prompt. After pressing @key{RET}, the tags will be +inserted and aligned to @code{org-tags-column}. When called with a +@kbd{C-u} prefix, all tags in the current buffer will be aligned to that +column, just to make things look nice. TAGS are automatically realigned +after promotion, demotion, and TODO state changes (@pxref{TODO basics}). +@end table + +@node Tag searches, , Setting tags, Tags +@section Tag searches +@cindex tag searches + +Once a tags system has been set up, it can be used to collect related +information into special lists. + +@table @kbd +@kindex C-c \ +@item C-c \ +Create a sparse tree with all headlines matching a tags search. +@kindex C-c a m +@item C-c a m +Create a global list of tag matches from all agenda files. +@xref{Matching headline tags}. +@kindex C-c a M +@item C-c a M +Create a global list of tag matches from all agenda files, but check +only TODO items and force checking subitems (see variable +@code{org-tags-match-list-sublevels}). +@end table + +A @i{tags} search string can use Boolean operators @samp{&} for AND and +@samp{|} for OR. @samp{&} binds more strongly than @samp{|}. +Parenthesis are currently not implemented. A tag may also be preceded +by @samp{-}, to select against it, and @samp{+} is syntactic sugar for +positive selection. The AND operator @samp{&} is optional when @samp{+} +or @samp{-} is present. For example, @samp{+WORK-BOSS} would select all +headlines that are tagged @samp{:WORK:}, but discard those also tagged +@samp{:BOSS:}. The search string @samp{WORK|LAPTOP} selects all lines +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 @chapter Agenda Views @cindex agenda views -Due to the way Org-mode works, TODO items and time-stamped items can -be scattered throughout a file or even a number of files. To get an -overview over open action items, or over events that are important for -a particular date, this information must be collected, sorted and -displayed in an organized way. +Due to the way Org-mode works, TODO items, time-stamped items, and +tagged headlines can be scattered throughout a file or even a number of +files. To get an overview over open action items, or over events that +are important for a particular date, this information must be collected, +sorted and displayed in an organized way. Org-mode can select items based on various criteria, and display them in a separate buffer. Three different views are provided: @@ -2233,7 +2351,7 @@ to visit any of them. The views are created through a dispatcher that should be bound to a global key, for example @kbd{C-c a} (@pxref{Installation and activation}). In the following we will assume that @kbd{C-c a} is -indeed how the dispatcher is accessed and lists keyboard access to +indeed how the dispatcher is accessed and list keyboard access to commands accordingly. After pressing @kbd{C-c a}, an additional letter is required to execute a command. The dispatcher offers the following default commands: @@ -3077,8 +3195,8 @@ variables is available with @kbd{M-x org-customize}. Or select @cindex clean outline view Some people find it noisy and distracting that the Org-mode headlines -are starting with a potentially large number of stars. For example in -the example tree from @ref{Headlines}: +are starting with a potentially large number of stars. For example +the tree from @ref{Headlines}: @example * Top level headline @@ -3236,11 +3354,6 @@ this. See the documentation on the command @code{make-indirect-buffer}. In XEmacs, this is currently not possible because of the different outline implementation. -@item @b{Is there an easy way to insert links to web locations?}@* -@cindex URL, paste into buffer -Sure, just type or paste them into the buffer. A plain-text URL-like -string is directly interpreted as a link. - @item @b{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?}@* @@ -3369,7 +3482,7 @@ packages is using calc for embedded calculations. @xref{Embedded Mode, @cindex @file{constants.el} @item @file{constants.el} by Carsten Dominik In a table formula (@pxref{Table calculations}), it is possible to use -names for natural constants or units. Instead of defining you own +names for natural constants or units. Instead of defining your own constants in the variable @code{org-table-formula-constants}, install the @file{constants} package which defines a large number of constants and units, and lets you use unit prefixes like @samp{M} for @@ -3399,27 +3512,27 @@ to have other replacement keys, look at the variable @item @file{remember.el} by John Wiegley Org mode cooperates with remember, see @ref{Remember}. @file{Remember.el} is not part of Emacs, find it on the web. -@cindex @file{planner.el} -@item @file{planner.el} by John Wiegley -Planner is another tool to plan work and keep track of tasks. Planner -uses a multi-file approach with project pages and day pages. Is it -based on Emacs-Wiki. If Planner is your primary tool, it can be useful -to display the agenda entries resulting from org files in day-pages of -the planner. This can be done through the diary of the calendar: -integrate org files into the diary as described above, and then turn on -the diary support of planner. Planner is not part of Emacs, find it on -the web. @end table @node Bugs, Acknowledgments, Interaction, Miscellaneous @section Bugs @cindex bugs -Here is a list of things which should work differently, but which I +Here is a list of things that should work differently, but which I have found too hard to fix. @itemize @bullet @item +If a table field starts with a link, and if the corresponding table +column is narrowed (@pxref{Narrow columns}) to a width too small to +display the link, the field would look entirely empty even though it is +not. To prevent this, Org-mode throws an error. The work-around is to +make the column wide enough to fit the link, or to add some text (at +least 2 characters) before the link in the same field. +@item +Narrowing table columns does not work on XEmacs, because the +@code{format} function does not transport text properties. +@item Text in an entry protected with the @samp{QUOTE} keyword should not autowrap. @item @@ -3453,8 +3566,6 @@ several words in a row, each must have the emphasize markers, like in The exporters work well, but could be made more efficient. @end itemize -@page - @node Acknowledgments, , Bugs, Miscellaneous @section Acknowledgments @cindex acknowledgments @@ -3493,6 +3604,9 @@ general file links, and TAGS. @item Oliver Oppitz suggested multi-state TODO items. @item +Scott Otterson sparked the introduction of descriptive text for links, +among other things. +@item Pete Phillips helped the development of the TAGS feature. @item Matthias Rempe (Oelde) provided ideas, Windows support, and quality @@ -3516,7 +3630,10 @@ Chris Wallace provided a patch implementing the @samp{QUOTE} keyword. David Wainberg suggested archiving, and improvements to the linking system. @item -Scheduling TODO items was inspired by John Wiegley's @file{planner.el}. +Org-mode's linking system was an independent development, but with time +has evolved to work similar to John's implementation in +@file{emacs-wiki-mode}. In particular, I adopted his way to make the +link itself invisible and only show descriptive text. @item Carsten Wimmer suggested some changes and helped fix a bug in linking to GNUS. @@ -3527,7 +3644,7 @@ work on a tty. Piotr Zielinski wrote @file{org-mouse.el} and showed how to follow links with mouse-1. @end itemize - + @node Index, Key Index, Miscellaneous, Top @chapter Index diff --git a/orgcard.pdf b/orgcard.pdf index bc4ab234b..531759968 100644 Binary files a/orgcard.pdf and b/orgcard.pdf differ diff --git a/orgcard.tex b/orgcard.tex index 51a36971f..ed0c94dc5 100644 --- a/orgcard.tex +++ b/orgcard.tex @@ -1,5 +1,5 @@ % Reference Card for Org Mode -\def\orgversionnumber{4.13} +\def\orgversionnumber{4.19a} \def\year{2006} % %**start of header @@ -366,10 +366,8 @@ To set archive location for current file, add a line like$^3$: \key{insert SCHEDULED timestamp}{C-c C-s} \key{create sparse tree with all deadlines due}{C-c C-w} \key{the time between 2 dates in a time range}{C-c C-y} -\key{change timestamp at cursor by $-1$ day}{S-LEFT$^4$} -\key{change timestamp at cursor by $+1$ day}{S-RIGHT$^4$} -\key{change year/month/day at cursor by $-1$}{S-DOWN$^4$} -\key{change year/month/day at cursor by $+1$}{S-UP$^4$} +\key{change timestamp at cursor by $\pm 1$ day}{S-RIGHT/LEFT$^4$} +\key{change year/month/day at cursor by $\pm 1$}{S-UP/DOWN$^4$} \key{access the calendar for the current date}{C-c >} \key{insert timestamp matching date in calendar}{C-c <} \key{access agenda for current date}{C-c C-o} @@ -385,6 +383,7 @@ To set archive location for current file, add a line like$^3$: \key{globally store link to the current location}{C-c l$^2$} \key{insert a link (TAB completes stored links)}{C-c C-l} \key{insert file link with file name completion}{C-u C-c C-l} +\key{edit (also hidden part of) link at point}{C-c C-l} \key{open file links in emacs (\kbd{C-u} : in emacs)}{C-c C-o} \key{open link at point (3: in emacs)}{mouse-2/3} @@ -398,6 +397,7 @@ To set archive location for current file, add a line like$^3$: \key{\kbd{<<>>}}{\rm radio target$^3$} \key{\kbd{[[*this text]]}}{\rm find headline} \metax{\kbd{[[this text]]}}{\rm find target or text in buffer} +\metax{\kbd{[[this text][description]]}}{\rm optional link text} {\bf External Links} @@ -415,6 +415,7 @@ To set archive location for current file, add a line like$^3$: \key{\kbd{}}{\rm GNUS message} \key{\kbd{}}{\rm Mail folder} \key{\kbd{}}{\rm Mail message} +\metax{\kbd{[[][description]]}}{\rm optional link text} %\key{\kbd{}}{\rm VM remote} \section{Tables} @@ -424,8 +425,8 @@ To set archive location for current file, add a line like$^3$: {\bf Creating a table} -\metax{insert a new Org-mode table}{M-x org-table-create} -\metax{... or just start typing, e.g.}{|Name|Phone|Age RET |- TAB} +%\metax{insert a new Org-mode table}{M-x org-table-create} +\metax{just start typing, e.g.}{|Name|Phone|Age RET |- TAB} \key{convert region to table}{C-c C-c} \key{... separator at least 3 spaces}{C-3 C-c C-c} %\key{... prompt for separator regexp}{C-u C-c C-c} @@ -495,6 +496,7 @@ introduces a column formula, \kbd{:=} a named-field formula. {\bf Miscellaneous} +\key{edit the current field in a separate window}{C-c `} \key{toggle visibility of vertical lines}{C-c |} \metax{export as tab-separated file}{M-x org-table-export} \metax{import tab-separated file}{M-x org-table-import}