diff options
| author | Carsten Dominik <dominik@nb-dominik2.science.uva.nl> | 2008-01-31 11:30:30 +0100 |
|---|---|---|
| committer | Carsten Dominik <dominik@nb-dominik2.science.uva.nl> | 2008-01-31 11:30:30 +0100 |
| commit | dc8bc8e39230bde1eca569c564e65bf85c43de54 (patch) | |
| tree | 4494385b88271a3c675006fb2d36c80190acbe06 | |
| parent | 2b15c2fd30286e29bbf128f4437fa4b261911bf9 (diff) | |
Release 4.19brelease_4.19b
| -rw-r--r-- | org | 672 | ||||
| -rw-r--r-- | org.el | 2570 | ||||
| -rw-r--r-- | org.pdf | bin | 455156 -> 458240 bytes | |||
| -rw-r--r-- | org.texi | 254 | ||||
| -rw-r--r-- | orgcard.pdf | bin | 58659 -> 58579 bytes | |||
| -rw-r--r-- | orgcard.tex | 41 |
6 files changed, 1982 insertions, 1555 deletions
@@ -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.19a). + This manual is for Org-mode (version 4.19b). 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.19a). +This manual is for Org-mode (version 4.19b). Copyright (C) 2004, 2005, 2006 Free Software Foundation @@ -265,6 +265,12 @@ this: which will select Org-mode for this buffer no matter what the file's name is. See also the variable `org-insert-mode-line-in-empty-file'. + If you are upgrading to version 4.20 or later from a version 4.14 or +earlier, some links may stop working. These are links containing space +characters. To make such links work again, and also to transform all +links from the old `<link>' format to the new `[[link]]' format, +execute once in each file: `M-x org-upgrade-old-links'. + File: org, Node: Feedback, Prev: Installation and activation, Up: Introduction @@ -281,6 +287,7 @@ including the version information of Emacs (`C-h v emacs-version Org-mode related setup in `.emacs'. If an error occurs, a traceback can be very useful. Often a small example file helps, along with clear information about: + 1. What exactly did you do? 2. What did you expect to happen? @@ -339,9 +346,10 @@ Org-mode start with one or more stars, on the left margin. For example: *** 3rd level more text * Another top level headline - Some people find the many stars too noisy and would prefer an -outline that has whitespace followed by a single star as headline -starters. *Note Clean view:: describes a setup to realize this. + +Some people find the many stars too noisy and would prefer an outline +that has whitespace followed by a single star as headline starters. +*Note Clean view:: describes a setup to realize this. File: org, Node: Visibility cycling, Next: Motion, Prev: Headlines, Up: Document Structure @@ -355,15 +363,19 @@ visibility in the buffer. `<TAB>' Rotate current subtree between the states + ,-> FOLDED -> CHILDREN -> SUBTREE --. '-----------------------------------' + At the beginning of the buffer (or when called with `C-u'), this does the same as the command `S-<TAB>' below. `S-<TAB>' Rotate the entire buffer between the states + ,-> OVERVIEW -> CONTENTS -> SHOW ALL --. '--------------------------------------' + Note that inside tables, `S-<TAB>' jumps to the previous field. `C-c C-a' @@ -512,10 +524,12 @@ use the variable `org-agenda-custom-commands' to define fast keyboard access to specific sparse trees. These commands will then be accessible through the agenda dispatcher (*note Agenda dispatcher::). For example: + (setq org-agenda-custom-commands '(("f" occur-tree "FIXME"))) - will define the key `C-c a f' as a shortcut for creating a sparse -tree matching the string `FIXME'. + +will define the key `C-c a f' as a shortcut for creating a sparse tree +matching the string `FIXME'. Other commands are using sparse trees as well. For example `C-c C-v' creates a sparse TODO tree (*note TODO basics::). @@ -653,7 +667,8 @@ only type |Name|Phone|Age |- - and then press <TAB> to align the table and start filling in fields. + +and then press <TAB> to align the table and start filling in fields. When typing text into a field, Org-mode treats <DEL>, <Backspace>, and all character keys in a special way, so that inserting and deleting @@ -811,7 +826,13 @@ Miscellaneous `C-c `' Edit the current field in a separate window. This is useful for - fields that are not fully visible (*note Narrow columns::). + fields that are not fully visible (*note Narrow columns::). When + called with a `C-u' prefix, just make the full field visible, so + that it can be edited in place. + +`C-c <TAB>' + This is an alias for `C-u C-c `' to make the current field fully + visible. `C-c |' Toggle the visibility of vertical lines in tables. The lines are @@ -835,8 +856,10 @@ Miscellaneous If you don't like the automatic table editor because it gets in your way on lines which you would like to start with `|', you can turn it off with + (setq org-enable-table-editor nil) - The only table command which then still works is `C-c C-c' to do a + +The only table command which then still works is `C-c C-c' to do a manual re-align. @@ -860,9 +883,10 @@ to no more than this value. | 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 + +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'. @@ -873,6 +897,7 @@ 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 @@ -947,6 +972,7 @@ or fixed display format, respectively, and `D', `R', `F', and `S' to turn on degrees, radians, fraction and symbolic modes, respectively. In addition, you may provide a `printf' format specifier to reformat the final result. A few examples: + $1+$2 Sum of first and second field $1+$2;%.2f Same, format result to two decimals exp($2)+exp($1) Math functions can be used @@ -1013,6 +1039,7 @@ you want to be able to assign a formula to an individual field (instead of an entire column) you need to reserve the first column of the table for special marking characters. Here is an example of a table that collects exam results of students and makes use of these features: + |---+---------+--------+--------+--------+-------+------| | | Student | Prob 1 | Prob 2 | Prob 3 | Total | Note | |---+---------+--------+--------+--------+-------+------| @@ -1157,6 +1184,7 @@ might want to use it also in other modes like text-mode or mail-mode. The minor mode Orgtbl-mode makes this possible. You can always toggle the mode with `M-x orgtbl-mode'. To turn it on by default, for example in mail mode, use + (add-hook 'mail-mode-hook 'turn-on-orgtbl) @@ -1209,24 +1237,24 @@ File: org, Node: Link format, Next: Internal links, Prev: Hyperlinks, Up: Hy =============== 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: +them as clickable links. However, the general linkformat looks like +this: + [[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 <BACKSPACE> 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. +C-l' with the cursor on the link. If you place the cursor at the +beginning of end of the displayed text and press <BACKSPACE>, you will +remove the (invisible) bracket at that location. This makes the link +incomplete and the internals are again displayed as plain text. +Inserting the missing bracket does hide the link internal again. +Finally, 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 @@ -1242,6 +1270,7 @@ 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 + # <<My Target>> If no dedicated target exists, Org-mode will search for the words in @@ -1251,6 +1280,7 @@ star like `*My Target' restrict the search to headlines. When searching, Org-mode will first try an exact match, but then move on to more and more lenient searches. For example, the link `[[*My Targets]]' will find any of the following: + ** My targets ** TODO my targets are bright ** my 20 targets are @@ -1293,11 +1323,13 @@ File: org, Node: CamelCase links, Prev: Radio targets, Up: Internal links 4.2.2 CamelCase words as links ------------------------------ -As an alternative to `[[...]]' links, Org-mode also supports CamelCase -words as links. This feature is not turned on by default because of -the occasional inconsistencies this system suffers from. To activate -CamelCase words as links, and to make headline completion offer -CamelCase version of headlines, the following customization is needed: +Org-mode also supports CamelCase words as links. This feature is not +turned on by default because of the inconsistencies this system suffers +from. It is mainly kept for backward compatibility, but the use is +deprecated. To activate CamelCase words as links, and to make headline +completion offer CamelCase version of headlines, the following +customization is needed: + (setq org-activate-camels t org-file-link-context-use-camel-case t) @@ -1308,40 +1340,37 @@ File: org, Node: External links, Next: Managing links, Prev: Internal links, ================== Org-mode supports links to files, websites, Usenet and email messages; -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. - - <http://www.astro.uva.nl/~dominik> on the web - <file:/home/dominik/images/jupiter.jpg> file, absolute path - <file:papers/last.pdf> file, relative path - <news:comp.emacs> Usenet link - <mailto:adent@galaxy.net> Mail link - <vm:folder> VM folder link - <vm:folder#id> VM message link - <vm://myself@some.where.org/folder#id> VM on remote machine - <wl:folder> WANDERLUST folder link - <wl:folder#id> WANDERLUST message link - <mhe:folder> MH-E folder link - <mhe:folder#id> MH-E message link - <rmail:folder> RMAIL folder link - <rmail:folder#id> RMAIL message link - <gnus:group> GNUS group link - <gnus:group#id> GNUS article link - <bbdb:Richard Stallman> BBDB link - <shell:ls *.org>(1) A shell command - - A link may contain space characters and is terminated by `>' 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. - - To display a descriptive text instead of the URL, enclose the link -into double brackets and add the descriptive text like this: - [[<http://www.gnu.org/software/emacs/>][GNU Emacs]] - Links inserted with `C-c C-l' automatically use the double bracket -format (*note Managing links::). +and BBDB database entries. External links are URL-like locators. The +following list shows examples for each link type. + + http://www.astro.uva.nl/~dominik on the web + file:/home/dominik/images/jupiter.jpg file, absolute path + file:papers/last.pdf file, relative path + news:comp.emacs Usenet link + mailto:adent@galaxy.net Mail link + vm:folder VM folder link + vm:folder#id VM message link + vm://myself@some.where.org/folder#id VM on remote machine + wl:folder WANDERLUST folder link + wl:folder#id WANDERLUST message link + mhe:folder MH-E folder link + mhe:folder#id MH-E message link + rmail:folder RMAIL folder link + rmail:folder#id RMAIL message link + gnus:group GNUS group link + gnus:group#id GNUS article link + bbdb:Richard Stallman BBDB link + shell:ls *.org(1) A shell command + + A link should be enclosed in double brackets and may contain a +descriptive text to be displayed instead of the url (*note Link +format::), for example: + + [[http://www.gnu.org/software/emacs/][GNU Emacs]] + + Org-mode also finds external links in the normal text and activates +them as links. Plain text links cannot contain spaces. To remove +ambiguities about the end of the link, enclose them in angular brackets. ---------- Footnotes ---------- @@ -1376,31 +1405,41 @@ insert it into an org-mode file, and to follow the link. 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. + session can be accessed. The link will be formatted as given in + the variable `org-link-format' and inserted into the buffer, along + with a descriptive text. Note that you don't have to use this + command to insert a link. Links in Org-mode are plain text, and + you can type or paste them straight into the buffer. By using + this command, the links are automatically enclosed in double + brackets, and you will be asked for the optional descriptive text. + +`C-u C-c C-l' + When `C-c C-l' is called with a `C-u' prefix argument, a link to a + file will be inserted and you may use file name completion to + select the name of the file. The path to the file is inserted + relative to the directory of the current org file, if the linked + file is in the current directory or in a subdirectory of it. + Otherwise an absolute path, if possible with `~/' for your home + directory is used. You can force an absolute path with two `C-u' + prefixes. + +`C-c C-l with cursor on existing link' + When the cursor is on an existing link, `C-c C-l' allows to edit + the link and description parts of the link. `C-c C-o' 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 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 - application for non-text files. Classification of files is based - on file extension only. See option `org-file-apps'. If there is - no link at point, the current subtree will be searched for one. - If you want to override the default application and visit the file - with Emacs, use a `C-u' prefix. If the cursor is on a time stamp, - it compiles the agenda for that date. - - *IMPORTANT*: Be careful not to use any dangerous commands in a - shell link. + `browse-url-at-point'), run vm/mh-e/wanderlust/rmail/gnus/bbdb for + the corresponding links, and execute the command in a shell link. + When the cursor is on an internal link, this commands runs the + corresponding search. When the cursor is on a TAGS list in a + headline, it creates the corresponding TAGS view. If the cursor + is on a time stamp, it compiles the agenda for that date. + Furthermore, it will visit text files in `file:' links with Emacs + and select a suitable application for non-text files. + Classification of files is based on file extension only. See + option `org-file-apps'. If you want to override the default + application and visit the file with Emacs, use a `C-u' prefix. `mouse-2' `mouse-1' @@ -1429,11 +1468,13 @@ File: org, Node: Search Options, Next: Remember, Prev: Managing links, Up: H File links can contain additional information to make Emacs jump to a particular location in the file when following a link. This can be a line number or a search option after a double(1) colon. For example: - <file:~/code/main.c::255> - <file:~/xx.org::My Target> - <file:~/xx.org::*My Target> - <file:~/xx.org::/regexp/> - Here is what these options do. + + [[file:~/code/main.c::255]] + [[file:~/xx.org::My Target]] + [[file:~/xx.org::*My Target]] + [[file:~/xx.org::/regexp/]] + +Here is what these options do. `255' Jump to line 255. @@ -1495,8 +1536,9 @@ journal entries, you could use: (setq org-remember-templates '((?t "* TODO %?\n %i\n %a" "~/org/TODO.org") (?j "* %U %?\n\n %i\n %a" "~/org/JOURNAL.org"))) - In these entries, the character specifies how to select the -template, the first string specifies the template, and the second string + +In these entries, the character specifies how to select the template, +the first string specifies the template, and the second string specifies a default file (overruling `org-default-notes-file') as a target for this note. @@ -1504,7 +1546,9 @@ target for this note. for a key to select the template and then prepare the buffer like * TODO <file:link to where you called remember> - or + +or + * [2006-03-21 Tue 15:37] <file:link to where you called remember> @@ -1587,8 +1631,10 @@ The most important commands to work with TODO entries are: `C-c C-t' Rotate the TODO state of the current item between + ,-> (unmarked) -> TODO -> DONE --. '--------------------------------' + The same rotation can also be done "remotely" from the timeline and agenda buffers with the `t' command key (*note Agenda commands::). @@ -1619,15 +1665,17 @@ File: org, Node: Progress logging, Next: TODO extensions, Prev: TODO basics, If you want to keep track of _when_ a certain TODO item was finished, turn on logging with + (setq org-log-done t) - Then each time you turn a TODO entry into DONE using either `C-c -C-t' in the Org-mode buffer or `t' in the agenda buffer, a line -`CLOSED: [timestamp]' will be inserted just after the headline. If you -turn the entry back into a TODO item again through further state -cycling, that line will be removed again. In the timeline (*note -Timeline::) and in the agenda (*note Weekly/Daily Agenda::), you can -then use the `L' key to display the TODO items closed on each day, -giving you an overview of what has been done on a day. + +Then each time you turn a TODO entry into DONE using either `C-c C-t' +in the Org-mode buffer or `t' in the agenda buffer, a line `CLOSED: +[timestamp]' will be inserted just after the headline. If you turn the +entry back into a TODO item again through further state cycling, that +line will be removed again. In the timeline (*note Timeline::) and in +the agenda (*note Weekly/Daily Agenda::), you can then use the `L' key +to display the TODO items closed on each day, giving you an overview of +what has been done on a day. File: org, Node: TODO extensions, Next: Priorities, Prev: Progress logging, Up: TODO items @@ -1951,7 +1999,7 @@ File: org, Node: Tags, Next: Agenda Views, Prev: Timestamps, Up: Top ****** If you wish to implement a system to cross-correlate information, an -excellent ways is assigning tags to headline. Org-mode has extensive +excellent way is to assign tags to headline. Org-mode has extensive support for using tags. Every headline can contain a list of tags, at the end of the @@ -1978,8 +2026,9 @@ 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 + +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 @@ -2054,6 +2103,7 @@ 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: + * an _agenda_ that is like a calendar and shows information for specific dates @@ -2061,7 +2111,8 @@ in a separate buffer. Three different views are provided: * a _tags view_ that shows information based on the tags associated with headlines in the outline tree. - The extracted information is displayed in a special _agenda buffer_. + +The extracted information is displayed in a special _agenda buffer_. This buffer is read-only, but provides commands to visit the corresponding locations in the original Org-mode files, and even to edit these files remotely. @@ -2098,7 +2149,8 @@ way to maintain it is through the following commands `C-,' Cycle through agenda file list, visiting one file after the other. - The Org menu contains the current list of files and can be used to + +The Org menu contains the current list of files and can be used to visit any of them. ---------- Footnotes ---------- @@ -2145,12 +2197,14 @@ on the current buffer instead of the list of agenda files. `org-agenda-custom-commands'. You can customize this variable, for example by pressing `C-c a C'. You can also directly set it with Emacs Lisp in `.emacs'. For example: + (setq org-agenda-custom-commands '(("w" todo "WAITING") ("u" tags "+BOSS-URGENT") ("U" tags-tree "+BOSS-URGENT") ("f" occur-tree "\\<FIXME\\>"))) - will define `C-c a w' as a global search for TODO entries with + +will define `C-c a w' as a global search for TODO entries with `WAITING' as the TODO keyword, `C-c a u' as a global tags search for headlines marked `:BOSS:' but not `:URGENT:', `C-c a U' to do the same search but only in the current buffer and display the result as a @@ -2195,7 +2249,9 @@ File: org, Node: Categories, Next: Time-of-day specifications, Prev: Weekly/D In the agenda buffer, each entry is preceded by a _category_, which is derived from the file name. The category can also be set with a special line anywhere in the buffer, looking like this: + #+CATEGORY: Thesis + If there are several such lines in a file, each specifies the category for the text below it (but the first category also applies to any text before the first CATEGORY line). The display in the agenda @@ -2264,7 +2320,8 @@ the diary. agenda, you only need to customize the variable (setq org-agenda-include-diary t) - After that, everything will happen automatically. All diary entries + +After that, everything will happen automatically. All diary entries including holidays, anniversaries etc will be included in the agenda buffer created by Org-mode. <SPC>, <TAB>, and <RET> can be used from the agenda buffer to jump to the diary file in order to edit existing @@ -2368,7 +2425,8 @@ is to give an overview over events in a project. Show a time-sorted view of the org file, with all time-stamped items. When called with a `C-u' prefix, all unfinished TODO entries (scheduled or not) are also listed under the current date. - The commands available in the timeline buffer are listed in *Note + +The commands available in the timeline buffer are listed in *Note Agenda commands::. @@ -2598,8 +2656,10 @@ headlines, defining a general document structure. Additional levels will be exported as itemized lists. If you want that transition to occur at a different level, specify it with a prefix argument. For example, + C-1 C-c C-x a org-export-as-ascii - creates only top level headlines and does the rest as items. Lines + +creates only top level headlines and does the rest as items. Lines starting with `#' and subtrees starting with the word `COMMENT' will not be exported. @@ -2630,8 +2690,10 @@ headlines, defining a general document structure. Additional levels will be exported as itemized lists. If you want that transition to occur at a different level, specify it with a prefix argument. For example, + C-2 C-c C-x b - creates two levels of headings and does the rest as items. + +creates two levels of headings and does the rest as items. * Menu: @@ -2700,7 +2762,8 @@ Completion::). #+TEXT: Some descriptive text to be inserted at the beginning. #+TEXT: Several lines may be given. #+OPTIONS: H:2 num:t toc:t \n:nil t ::t |:t ^:t *:nil TeX:t - The OPTIONS line is a compact form to specify export settings. Here + +The OPTIONS line is a compact form to specify export settings. Here you can: H: set the number of headline levels for export num: turn on/off section-numbers @@ -2879,7 +2942,8 @@ the buffer) #+STARTUP: showstars #+STARTUP: hidestars - Press `C-c C-c' with the cursor in a `STARTUP' line to activate the + +Press `C-c C-c' with the cursor in a `STARTUP' line to activate the modifications. With stars hidden, the tree becomes: @@ -2983,19 +3047,35 @@ File: org, Node: FAQ, Next: Interaction, Prev: TTY keys, Up: Miscellaneous turn it on for all `README' files? (add-to-list 'auto-mode-alist '("README$" . org-mode)) - 2. All these stars are driving me mad, I just find the Emacs outlines + 2. Some of my links stopped working after I upgraded to a version + 4.20 or later. Why is this, and how can I fix it? + The newer versions of Org-mode have a better link system and no + longer allow unescaped space characters as part of a link. To fix + these links, and also to move all `<link>' style links to the new + `[[link]]' system, execute once in each Org-mode file: `M-x + org-upgrade-old-links'. + + 3. I really like the old style links with angular brackets better. + Please give them back to me, don't tell me it is not possible! + Would I let you down like that? If you must (even if I don't + understand why), you can do this + (setq org-allow-space-in-plain-links t + org-link-style 'plain + org-link-format "<%s>") + + 4. All these stars are driving me mad, I just find the Emacs outlines unreadable. Can't you just put white space and a single star as a starter for headlines? See *Note Clean view::. - 3. I would like to have two windows on the same Org-mode file, but + 5. I would like to have two windows on the same Org-mode file, but with different outline visibility. Is that possible? In GNU Emacs, you may use _indirect buffers_ which do exactly this. See the documentation on the command `make-indirect-buffer'. In XEmacs, this is currently not possible because of the different outline implementation. - 4. When I export my TODO list, every TODO item becomes a separate + 6. 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 @@ -3013,42 +3093,42 @@ File: org, Node: FAQ, Next: Interaction, Prev: TTY keys, Up: Miscellaneous +OPTIONS: H:2; ... - 5. I would like to export only a subtree of my file to HTML. How? + 7. 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. - 6. Org-mode takes over the S-cursor keys. I also want to use + 8. 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::. - 7. Is there an easy way to insert an empty table template with a + 9. 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 <TAB>. 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. - 8. One of my table columns has started to fill up with `#ERROR'. + 10. 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! - 9. When I am in the last column of a table and just above a + 11. 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 <down> (to get on the separator line) and then <TAB>. Or configure the variable `org-table-tab-jumps-over-hlines'. - 10. How can I change the indentation of an entire table without fixing + 12. 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 <TAB>. - 11. Is it possible to include entries from org-mode files into my + 13. 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 @@ -3128,9 +3208,11 @@ Org-mode can cooperate with the following packages: `org-CUA-compatible'. When set, Org-mode will move the following keybindings in org-mode files, and in the agenda buffer (but not during date selection). + S-UP -> M-p S-DOWN -> M-n S-LEFT -> M-- S-RIGHT -> M-+ S-RET -> C-S-RET + Yes, these are unfortunately more difficult to remember. If you want to have other replacement keys, look at the variable `org-disputed-keys'. @@ -3216,13 +3298,14 @@ Org-mode would not be what it is without your input. * Pavel Chalmoviansky influenced the agenda treatment of items with specified time. - * Sacha Chua suggested to copy linking code from Planner (we did take - some). + * Sacha Chua suggested to copy some linking code from Planner. * Christian Egli converted the documentation into TeXInfo format, patched CSS formatting into the HTML exporter, and inspired the agenda. + * Nic Ferrier contributed mailcap and XML support. + * Kai Grossjohann pointed out key-binding conflicts caused by Org-mode. @@ -3261,10 +3344,13 @@ Org-mode would not be what it is without your input. * David Wainberg suggested archiving, and improvements to the linking system. - * 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. + * John Wiegley wrote `emacs-wiki.el' and `planner.el'. The + development of Org-mode was fully independent, and both systems are + really different beasts in their basic ideas and implementation + details. However, I have later looked at John's code and learned + from his implementation of (i) links where the link itself is + hidden and only a description is shown, and (ii) popping up a + calendar to select a date. * Carsten Wimmer suggested some changes and helped fix a bug in linking to GNUS. @@ -3288,7 +3374,7 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * active region <1>: HTML export. (line 10) * active region <2>: ASCII export. (line 6) * active region <3>: Built-in table editor. - (line 166) + (line 167) * active region: Structure editing. (line 46) * agenda: Weekly/Daily Agenda. (line 6) * agenda commands, custom: Agenda dispatcher. (line 6) @@ -3296,6 +3382,7 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * agenda files, removing buffers: Agenda commands. (line 187) * agenda views: Agenda Views. (line 6) * agenda, for single file: Timeline. (line 6) +* angular brackets, around links: External links. (line 35) * applescript, for calendar update: iCalendar export. (line 38) * archive locations: Archiving. (line 13) * archiving: Archiving. (line 6) @@ -3311,7 +3398,7 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * calc.el: Interaction. (line 17) * calculations, in tables <1>: Table calculations. (line 6) * calculations, in tables: Built-in table editor. - (line 136) + (line 137) * calendar integration: Calendar/Diary integration. (line 6) * calendar, for selecting date: Creating timestamps. (line 68) @@ -3327,7 +3414,7 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * completion, of CamelCase links <1>: Completion. (line 6) * completion, of CamelCase links: CamelCase links. (line 6) * completion, of dictionary words: Completion. (line 6) -* completion, of file names: Managing links. (line 23) +* completion, of file names: Managing links. (line 36) * completion, of links: Managing links. (line 23) * completion, of option keywords <1>: Completion. (line 6) * completion, of option keywords: Export options. (line 6) @@ -3340,7 +3427,7 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * completion, of TODO keywords: Workflow states. (line 12) * constants, in calculations: Formula syntax. (line 26) * constants.el: Interaction. (line 27) -* contents, global visibility state: Visibility cycling. (line 17) +* contents, global visibility state: Visibility cycling. (line 19) * copying, of subtrees: Structure editing. (line 6) * creating timestamps: Creating timestamps. (line 6) * CUA.el: Interaction. (line 39) @@ -3364,10 +3451,10 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * editing tables: Tables. (line 6) * editing, of table formulas: Editing/debugging formulas. (line 6) -* emphasized text: Export options. (line 21) +* emphasized text: Export options. (line 22) * evaluate time range: Creating timestamps. (line 63) * exporting: Exporting. (line 6) -* exporting a subtree: FAQ. (line 42) +* exporting a subtree: FAQ. (line 58) * exporting, not: Comment lines. (line 6) * extended TODO keywords: TODO extensions. (line 6) * external links: External links. (line 6) @@ -3375,14 +3462,14 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * feedback: Feedback. (line 6) * file links: External links. (line 6) * file links, searching: Search Options. (line 6) -* file name completion: Managing links. (line 23) +* file name completion: Managing links. (line 36) * files, adding to agenda list: Agenda files. (line 12) * filing subtrees: Archiving. (line 6) * fixed width: HTML formatting. (line 28) -* fixed-width sections: Export options. (line 21) +* fixed-width sections: Export options. (line 22) * folded, subtree visibility state: Visibility cycling. (line 10) * folding, sparse trees: Sparse trees. (line 6) -* following links: Managing links. (line 36) +* following links: Managing links. (line 50) * format specifier: Formula syntax. (line 34) * format, of links: Link format. (line 6) * formula editing: Editing/debugging formulas. @@ -3392,14 +3479,14 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top (line 6) * formula, for table column: Column formulas. (line 6) * formula, in tables: Built-in table editor. - (line 136) + (line 137) * global keybindings: Installation and activation. (line 6) * global TODO list: Global TODO list. (line 6) -* global visibility states: Visibility cycling. (line 17) +* global visibility states: Visibility cycling. (line 19) * GNUS links: External links. (line 6) * hand-formatted lists: HTML formatting. (line 9) -* headline levels: Export options. (line 21) +* headline levels: Export options. (line 22) * headline levels, for exporting <1>: HTML export. (line 22) * headline levels, for exporting: ASCII export. (line 12) * headline navigation: Motion. (line 6) @@ -3412,8 +3499,8 @@ 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 73) -* indirect buffers: FAQ. (line 18) +* indentation, of tables: FAQ. (line 89) +* indirect buffers: FAQ. (line 34) * inheritance, of tags: Tag inheritance. (line 6) * inserting links: Managing links. (line 23) * installation: Installation and activation. @@ -3425,20 +3512,20 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * keybindings, global: Installation and activation. (line 6) * keyword options: Per file keywords. (line 6) -* linebreak preservation: Export options. (line 21) +* linebreak preservation: Export options. (line 22) * 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 66) +* links, returning to: Managing links. (line 76) * 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 62) -* marking characters, tables: Advanced features. (line 33) +* make-indirect-buffer: FAQ. (line 34) +* mark ring: Managing links. (line 72) +* marking characters, tables: Advanced features. (line 34) * matching, of tags: Matching headline tags. (line 6) * matching, tags: Tags. (line 6) @@ -3464,24 +3551,25 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * outline tree: Headlines. (line 6) * outline-mode: Outlines. (line 6) * outlines: Outlines. (line 6) -* overview, global visibility state: Visibility cycling. (line 17) +* overview, global visibility state: Visibility cycling. (line 19) * packages, interaction with other: Interaction. (line 6) * pasting, of subtrees: Structure editing. (line 6) * per file keywords: Per file keywords. (line 6) * plain lists: Plain Lists. (line 6) -* printing sparse trees: Sparse trees. (line 37) +* plain text external links: External links. (line 35) +* printing sparse trees: Sparse trees. (line 39) * priorities: Priorities. (line 6) * priorities, of agenda items: Sorting of agenda items. (line 6) * progress logging: Progress logging. (line 6) * promotion, of subtrees: Structure editing. (line 6) -* quoted html tags: Export options. (line 21) +* quoted html tags: Export options. (line 22) * ranges, time: Time stamps. (line 6) * recomputing table fields: Column formulas. (line 27) * region, active <1>: HTML export. (line 10) * region, active <2>: ASCII export. (line 6) * region, active <3>: Built-in table editor. - (line 166) + (line 167) * region, active: Structure editing. (line 46) * remember.el <1>: Interaction. (line 39) * remember.el: Remember. (line 6) @@ -3489,17 +3577,17 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * SCHEDULED keyword: Time stamps. (line 39) * scheduling: Time stamps. (line 6) * search option in file links: Search Options. (line 6) -* section-numbers: Export options. (line 21) +* section-numbers: Export options. (line 22) * 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) +* show all, command: Visibility cycling. (line 27) +* show all, global visibility state: Visibility cycling. (line 19) * show hidden text: Visibility cycling. (line 6) * single file summary: Timeline. (line 6) * sorting, of agenda items: Sorting of agenda items. (line 6) * sparse tree, for deadlines: Creating timestamps. (line 38) -* sparse tree, for TODO: TODO basics. (line 18) +* sparse tree, for TODO: TODO basics. (line 20) * sparse tree, tag based: Tags. (line 6) * sparse trees: Sparse trees. (line 6) * spreadsheet capabilities: Table calculations. (line 6) @@ -3515,11 +3603,11 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * table editor, builtin: Built-in table editor. (line 6) * table editor, table.el: table.el. (line 6) -* table of contents: Export options. (line 21) -* table, empty template: FAQ. (line 52) +* table of contents: Export options. (line 22) +* table, empty template: FAQ. (line 68) * table.el <1>: Interaction. (line 13) * table.el: table.el. (line 6) -* tables <1>: Export options. (line 21) +* tables <1>: Export options. (line 22) * tables: Tables. (line 6) * tables, export to HTML: HTML formatting. (line 24) * tag completion: Completion. (line 6) @@ -3529,9 +3617,9 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top (line 6) * templates, for remember: Remember. (line 26) * TeX interpretation: HTML formatting. (line 15) -* TeX macros: Export options. (line 21) +* TeX macros: Export options. (line 22) * TeX symbol completion: Completion. (line 6) -* TeX-like syntax for sub- and superscripts: Export options. (line 21) +* TeX-like syntax for sub- and superscripts: Export options. (line 22) * thanks: Acknowledgments. (line 6) * time stamps: Time stamps. (line 6) * time, reading in minibuffer: Creating timestamps. (line 68) @@ -3548,7 +3636,7 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * transient-mark-mode <1>: HTML export. (line 10) * transient-mark-mode <2>: ASCII export. (line 6) * transient-mark-mode <3>: Built-in table editor. - (line 166) + (line 167) * transient-mark-mode: Structure editing. (line 46) * trees, sparse: Sparse trees. (line 6) * trees, visibility: Visibility cycling. (line 6) @@ -3560,7 +3648,7 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * variables, for customization: Customization. (line 6) * vectors, in table calculations: Formula syntax. (line 23) * visibility cycling: Visibility cycling. (line 6) -* visible text, printing: Sparse trees. (line 37) +* visible text, printing: Sparse trees. (line 39) * VM links: External links. (line 6) * WANDERLUST links: External links. (line 6) * workflow states as TODO keywords: Workflow states. (line 6) @@ -3584,12 +3672,12 @@ File: org, Node: Key Index, Prev: Index, Up: Top * <RET> <1>: Agenda commands. (line 41) * <RET> <2>: Creating timestamps. (line 100) * <RET>: Built-in table editor. - (line 65) + (line 66) * <right>: Agenda commands. (line 81) * <SPC>: Agenda commands. (line 28) * <TAB> <1>: Agenda commands. (line 35) * <TAB> <2>: Built-in table editor. - (line 58) + (line 59) * <TAB> <3>: Plain Lists. (line 37) * <TAB>: Visibility cycling. (line 10) * > <1>: Agenda commands. (line 140) @@ -3597,42 +3685,44 @@ File: org, Node: Key Index, Prev: Index, Up: Top * C: Agenda commands. (line 170) * c: Agenda commands. (line 154) * C-#: Built-in table editor. - (line 156) + (line 157) * C-,: Agenda files. (line 18) * C-c !: Creating timestamps. (line 21) * C-c $: Archiving. (line 9) -* C-c %: Managing links. (line 62) -* C-c &: Managing links. (line 66) +* C-c %: Managing links. (line 72) +* C-c &: Managing links. (line 76) * C-c ' <1>: Editing/debugging formulas. (line 20) * C-c ': Built-in table editor. - (line 145) + (line 146) * C-c *: Built-in table editor. - (line 149) + (line 150) * C-c +: Built-in table editor. - (line 166) + (line 167) * C-c ,: Priorities. (line 18) * C-c -: Built-in table editor. - (line 93) + (line 94) * C-c .: Creating timestamps. (line 10) * C-c /: Sparse trees. (line 15) * C-c :: HTML export. (line 17) * C-c ;: Comment lines. (line 12) * C-c <: Creating timestamps. (line 25) +* C-c <TAB>: Built-in table editor. + (line 189) * C-c =: Built-in table editor. - (line 136) + (line 137) * C-c >: Creating timestamps. (line 29) * C-c ? <1>: Editing/debugging formulas. (line 20) * C-c ?: Built-in table editor. - (line 162) + (line 163) * C-c [: Agenda files. (line 12) * C-c \: Tag searches. (line 9) * C-c ]: Agenda files. (line 15) * C-c ^: Built-in table editor. - (line 97) + (line 98) * C-c `: Built-in table editor. - (line 182) + (line 183) * C-c a a: Weekly/Daily Agenda. (line 9) * C-c a C: Agenda dispatcher. (line 30) * C-c a M: Matching headline tags. @@ -3643,15 +3733,15 @@ File: org, Node: Key Index, Prev: Index, Up: Top * 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 a t: TODO basics. (line 27) +* C-c C-a: Visibility cycling. (line 27) * C-c C-b: Motion. (line 15) * 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 <4>: Built-in table editor. - (line 43) + (line 44) * C-c C-c: Plain Lists. (line 61) * C-c C-d: Creating timestamps. (line 37) * C-c C-f: Motion. (line 12) @@ -3659,17 +3749,17 @@ File: org, Node: Key Index, Prev: Index, Up: Top * 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 36) +* C-c C-o: Managing links. (line 50) * C-c C-p: Motion. (line 9) * C-c C-q <1>: Editing/debugging formulas. (line 20) * C-c C-q: Built-in table editor. - (line 120) + (line 121) * C-c C-r: Timeline. (line 13) * C-c C-s: Creating timestamps. (line 47) * C-c C-t: TODO basics. (line 13) * C-c C-u: Motion. (line 18) -* C-c C-v: TODO basics. (line 18) +* C-c C-v: TODO basics. (line 20) * C-c C-w: Creating timestamps. (line 38) * C-c C-x a: ASCII export. (line 6) * C-c C-x b: HTML export. (line 11) @@ -3678,26 +3768,27 @@ File: org, Node: Key Index, Prev: Index, Up: Top * C-c C-x C-i: iCalendar export. (line 15) * C-c C-x C-k: Structure editing. (line 31) * C-c C-x C-w <1>: Built-in table editor. - (line 109) + (line 110) * C-c C-x C-w: Structure editing. (line 31) * C-c C-x C-y <1>: Built-in table editor. - (line 113) + (line 114) * C-c C-x C-y: Structure editing. (line 38) * C-c C-x h: HTML export. (line 10) * C-c C-x i: iCalendar export. (line 13) * C-c C-x M-w <1>: Built-in table editor. - (line 106) + (line 107) * C-c C-x M-w: Structure editing. (line 35) * C-c C-x t: HTML export. (line 14) -* C-c C-x v: Sparse trees. (line 37) +* C-c C-x v: Sparse trees. (line 39) * C-c C-y: Creating timestamps. (line 63) * C-c l: Managing links. (line 9) * C-c |: Built-in table editor. - (line 186) + (line 193) * C-c ~: table.el. (line 18) * C-u C-c .: Creating timestamps. (line 16) * C-u C-c =: Built-in table editor. - (line 140) + (line 141) +* C-u C-c C-l: Managing links. (line 36) * D: Agenda commands. (line 66) * d: Agenda commands. (line 63) * f: Agenda commands. (line 44) @@ -3708,46 +3799,46 @@ File: org, Node: Key Index, Prev: Index, Up: Top * L: Agenda commands. (line 32) * M: Agenda commands. (line 161) * M-<down>: Built-in table editor. - (line 83) + (line 84) * M-<left> <1>: Built-in table editor. - (line 73) + (line 74) * M-<left>: Structure editing. (line 13) * M-<RET> <1>: Plain Lists. (line 42) * M-<RET>: Structure editing. (line 6) * M-<right> <1>: Built-in table editor. - (line 73) + (line 74) * M-<right>: Structure editing. (line 16) * M-<TAB> <1>: Completion. (line 10) * M-<TAB> <2>: Setting tags. (line 6) * M-<TAB>: Per file keywords. (line 17) * M-<up>: Built-in table editor. - (line 83) + (line 84) * M-S-<down> <1>: Built-in table editor. - (line 90) + (line 91) * M-S-<down> <2>: Plain Lists. (line 46) * M-S-<down>: Structure editing. (line 28) * M-S-<left> <1>: Creating timestamps. (line 97) * M-S-<left> <2>: Built-in table editor. - (line 77) + (line 78) * M-S-<left> <3>: Plain Lists. (line 52) * M-S-<left>: Structure editing. (line 19) * M-S-<RET>: Structure editing. (line 10) * M-S-<right> <1>: Creating timestamps. (line 94) * M-S-<right> <2>: Built-in table editor. - (line 80) + (line 81) * M-S-<right> <3>: Plain Lists. (line 52) * M-S-<right>: Structure editing. (line 22) * M-S-<up> <1>: Built-in table editor. - (line 87) + (line 88) * M-S-<up> <2>: Plain Lists. (line 46) * M-S-<up>: Structure editing. (line 25) * mouse-1 <1>: Agenda commands. (line 35) * mouse-1 <2>: Creating timestamps. (line 79) -* mouse-1: Managing links. (line 54) +* mouse-1: Managing links. (line 64) * mouse-2 <1>: Agenda commands. (line 35) -* mouse-2: Managing links. (line 54) +* mouse-2: Managing links. (line 64) * mouse-3 <1>: Agenda commands. (line 28) -* mouse-3: Managing links. (line 59) +* mouse-3: Managing links. (line 69) * n: Agenda commands. (line 19) * o: Agenda commands. (line 57) * P: Agenda commands. (line 115) @@ -3762,12 +3853,12 @@ File: org, Node: Key Index, Prev: Index, Up: Top * S-<left> <1>: Agenda commands. (line 136) * S-<left>: Creating timestamps. (line 50) * S-<RET>: Built-in table editor. - (line 171) + (line 172) * S-<right> <1>: Agenda commands. (line 128) * S-<right>: Creating timestamps. (line 50) * S-<TAB> <1>: Built-in table editor. - (line 62) -* S-<TAB>: Visibility cycling. (line 17) + (line 63) +* S-<TAB>: Visibility cycling. (line 19) * S-<up> <1>: Agenda commands. (line 118) * S-<up> <2>: Creating timestamps. (line 55) * S-<up>: Priorities. (line 25) @@ -3783,94 +3874,93 @@ 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 +Node: Feedback11612 +Node: Document Structure12398 +Node: Outlines13164 +Node: Headlines13824 +Node: Visibility cycling14447 +Node: Motion15638 +Node: Structure editing16422 +Node: Archiving18165 +Node: Sparse trees19025 +Ref: Sparse trees-Footnote-121054 +Ref: Sparse trees-Footnote-221146 +Node: Plain Lists21260 +Ref: Plain Lists-Footnote-124016 +Node: Tables24373 +Node: Built-in table editor24921 +Node: Narrow columns32811 +Ref: Narrow columns-Footnote-134744 +Node: Table calculations34790 +Node: Formula syntax35966 +Ref: Formula syntax-Footnote-138900 +Node: Column formulas39199 +Node: Advanced features40961 +Node: Named-field formulas44216 +Node: Editing/debugging formulas44856 +Node: Appetizer46614 +Node: orgtbl-mode47716 +Node: table.el48207 +Node: Hyperlinks49184 +Node: Link format49818 +Node: Internal links51000 +Node: Radio targets52890 +Node: CamelCase links53605 +Node: External links54204 +Ref: External links-Footnote-156129 +Node: Managing links56268 +Node: Search Options60246 +Ref: Search Options-Footnote-161566 +Node: Remember61647 +Ref: Remember-Footnote-165528 +Node: TODO items65652 +Node: TODO basics66575 +Node: Progress logging68090 +Node: TODO extensions68876 +Node: Workflow states69676 +Node: TODO types70544 +Ref: TODO types-Footnote-172202 +Node: Per file keywords72284 +Ref: Per file keywords-Footnote-173737 +Node: Priorities73965 +Node: Timestamps75174 +Node: Time stamps75495 +Node: Creating timestamps77510 +Node: Tags80639 +Node: Tag inheritance81374 +Node: Setting tags82311 +Node: Tag searches83273 +Node: Agenda Views84482 +Node: Agenda files86021 +Ref: Agenda files-Footnote-186981 +Ref: Agenda files-Footnote-287130 +Node: Agenda dispatcher87322 +Node: Weekly/Daily Agenda89452 +Node: Categories90587 +Node: Time-of-day specifications91235 +Node: Calendar/Diary integration93211 +Node: Sorting of agenda items94588 +Node: Global TODO list95420 +Node: Matching headline tags96835 +Node: Timeline97778 +Node: Agenda commands98651 +Node: Exporting103906 +Node: ASCII export104478 +Node: HTML export105313 +Node: HTML formatting106429 +Node: Export options108061 +Node: Comment lines110252 +Node: iCalendar export110722 +Node: Miscellaneous112517 +Node: Completion113144 +Node: Customization114140 +Node: Clean view114588 +Node: TTY keys117228 +Node: FAQ118829 +Node: Interaction124335 +Node: Bugs127176 +Node: Acknowledgments129485 +Node: Index132415 +Node: Key Index152984 End Tag Table @@ -5,7 +5,7 @@ ;; Author: Carsten Dominik <dominik at science dot uva dot nl> ;; Keywords: outlines, hypermedia, calendar, wp ;; Homepage: http://www.astro.uva.nl/~dominik/Tools/org/ -;; Version: 4.19a +;; Version: 4.19b ;; ;; This file is part of GNU Emacs. ;; @@ -87,6 +87,7 @@ ;; - 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. +;; - Bug fixes. ;; ;; Version 4.13 ;; - The list of agenda files can be maintainted in an external file. @@ -155,7 +156,9 @@ ;; ;;; Code: -(eval-when-compile (require 'cl) (require 'calendar)) +(eval-when-compile + (require 'cl) + (require 'calendar)) (require 'outline) (require 'time-date) (require 'easymenu) @@ -166,7 +169,7 @@ ;;; Customization variables -(defvar org-version "4.19a" +(defvar org-version "4.19b" "The version number of the file org.el.") (defun org-version () (interactive) @@ -176,6 +179,7 @@ ;; of outline.el. (defconst org-noutline-p (featurep 'noutline) "Are we using the new outline mode?") +(defconst org-xemacs-p (featurep 'xemacs)) (defconst org-format-transports-properties-p (let ((x "a")) (add-text-properties 0 1 '(test t) x) @@ -216,7 +220,7 @@ uninteresting. Also tables look terrible when wrapped." :type 'boolean) (defcustom org-startup-align-all-tables nil - "Non-nil means, allign all tables when visiting a file. + "Non-nil means, align all tables when visiting a file. This is useful when the column width in tables is forced with <N> cookies in table fields. Such tables will look correct only after the first re-align." :group 'org-startup @@ -282,61 +286,24 @@ 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-ellipsis nil + "The ellipsis to use in the Org-mode outline. +When nil, just use the standard three dots. When a string, use that instead, +and just in Org-mode (which will then use its own display table). +Changing this requires executing `M-x org-mode' in a buffer to become +effective." + :group 'org-startup + :type '(choice (const :tag "Default" nil) + (string :tag "String" :value "...#"))) + +(defvar org-display-table nil + "The display table for org-mode, in case `org-ellipsis' is non-nil.") + (defgroup org-keywords nil - "Options concerning TODO items in Org-mode." + "Keywords in Org-mode." :tag "Org Keywords" :group 'org) -(defcustom org-todo-keywords '("TODO" "DONE") - "List of TODO entry keywords. -\\<org-mode-map>By default, this is '(\"TODO\" \"DONE\"). The last entry in the list is -considered to mean that the entry is \"done\". All the other mean that -action is required, and will make the entry show up in todo lists, diaries -etc. -The command \\[org-todo] cycles an entry through these states, and an -additional state where no keyword is present. For details about this -cycling, see also the variable `org-todo-interpretation' -Changes become only effective after restarting Emacs." - :group 'org-keywords - :type '(repeat (string :tag "Keyword"))) - -(defcustom org-todo-interpretation 'sequence - "Controls how TODO keywords are interpreted. -\\<org-mode-map>Possible values are `sequence' and `type'. -This variable is only relevant if `org-todo-keywords' contains more than two -states. There are two ways how these keywords can be used: - -- As a sequence in the process of working on a TODO item, for example - (setq org-todo-keywords '(\"TODO\" \"STARTED\" \"VERIFY\" \"DONE\") - org-todo-interpretation 'sequence) - -- As different types of TODO items, for example - (setq org-todo-keywords '(\"URGENT\" \"RELAXED\" \"REMIND\" \"FOR_TOM\" \"DONE\") - org-todo-interpretation 'type) - -When the states are interpreted as a sequence, \\[org-todo] always cycles -to the next state, in order to walk through all different states. So with -\\[org-todo], you turn an empty entry into the state TODO. When you started -working on the item, you use \\[org-todo] again to switch it to \"STARTED\", -later to VERIFY and finally to DONE. - -When the states are interpreted as types, \\[org-todo] still cycles through -when it is called several times in direct succession, in order to initially -select the type. However, if not called immediately after a previous -\\[org-todo], it switches from each type directly to DONE. So with the -above example, you could use `\\[org-todo] \\[org-todo]' to label an entry -RELAXED. If you later return to this entry and press \\[org-todo] again, -RELAXED will not be changed REMIND, but directly to DONE. - -You can create a large number of types. To initially select a -type, it is then best to use \\[universal-argument] \\[org-todo] in order to specify the -type with completion. Of course, you can also type the keyword -directly into the buffer. M-TAB completes TODO keywords at the -beginning of a headline." - :group 'org-keywords - :type '(choice (const sequence) - (const type))) - (defcustom org-deadline-string "DEADLINE:" "String to mark deadline entries. A deadline is this string, followed by a time stamp. Should be a word, @@ -377,430 +344,22 @@ An entry can be toggled between QUOTE and normal with :group 'org-keywords :type 'string) -(defcustom org-after-todo-state-change-hook nil - "Hook which is run after the state of a TODO item was changed. -The new state (a string with a TODO keyword, or nil) is available in the -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?") -(make-variable-buffer-local 'org-todo-kwd-priority-p) -(defvar org-todo-kwd-max-priority nil - "Maximum priority of TODO items.") -(make-variable-buffer-local 'org-todo-kwd-max-priority) -(defvar org-ds-keyword-length 12 - "Maximum length of the Deadline and SCHEDULED keywords.") -(make-variable-buffer-local 'org-ds-keyword-length) -(defvar org-done-string nil - "The last string in `org-todo-keywords', indicating an item is DONE.") -(make-variable-buffer-local 'org-done-string) -(defvar org-todo-regexp nil - "Matches any of the TODO state keywords.") -(make-variable-buffer-local 'org-todo-regexp) -(defvar org-not-done-regexp nil - "Matches any of the TODO state keywords except the last one.") -(make-variable-buffer-local 'org-not-done-regexp) -(defvar org-todo-line-regexp nil - "Matches a headline and puts TODO state into group 2 if present.") -(make-variable-buffer-local 'org-todo-line-regexp) -(defvar org-nl-done-regexp nil - "Matches newline followed by a headline with the DONE keyword.") -(make-variable-buffer-local 'org-nl-done-regexp) -(defvar org-looking-at-done-regexp nil - "Matches the DONE keyword a point.") -(make-variable-buffer-local 'org-looking-at-done-regexp) -(defvar org-deadline-regexp nil - "Matches the DEADLINE keyword.") -(make-variable-buffer-local 'org-deadline-regexp) -(defvar org-deadline-time-regexp nil - "Matches the DEADLINE keyword together with a time stamp.") -(make-variable-buffer-local 'org-deadline-time-regexp) -(defvar org-deadline-line-regexp nil - "Matches the DEADLINE keyword and the rest of the line.") -(make-variable-buffer-local 'org-deadline-line-regexp) -(defvar org-scheduled-regexp nil - "Matches the SCHEDULED keyword.") -(make-variable-buffer-local 'org-scheduled-regexp) -(defvar org-scheduled-time-regexp nil - "Matches the SCHEDULED keyword together with a time stamp.") -(make-variable-buffer-local 'org-scheduled-time-regexp) - -(defvar org-category nil - "Variable used by org files to set a category for agenda display. -Such files should use a file variable to set it, for example - - -*- mode: org; org-category: \"ELisp\" - -or contain a special line - -#+CATEGORY: ELisp - -If the file does not specify a category, then file's base name -is used instead.") -(make-variable-buffer-local 'org-category) - -(defgroup org-time nil - "Options concerning time stamps and deadlines in Org-mode." - :tag "Org Time" - :group 'org) - -(defconst org-time-stamp-formats '("<%Y-%m-%d %a>" . "<%Y-%m-%d %a %H:%M>") - "Formats for `format-time-string' which are used for time stamps. -It is not recommended to change this constant.") - -(defcustom org-time-stamp-rounding-minutes 0 - "Number of minutes to round time stamps to upon insertion. -When zero, insert the time unmodified. Useful rounding numbers -should be factors of 60, so for example 5, 10, 15. -When this is not zero, you can still force an exact time-stamp by using -a double prefix argument to a time-stamp command like `C-c .' or `C-c !'." - :group 'org-time - :type 'integer) - -(defcustom org-deadline-warning-days 30 - "No. of days before expiration during which a deadline becomes active. -This variable governs the display in the org file." - :group 'org-time - :type 'number) - -(defcustom org-popup-calendar-for-date-prompt t - "Non-nil means, pop up a calendar when prompting for a date. -In the calendar, the date can be selected with mouse-1. However, the -minibuffer will also be active, and you can simply enter the date as well. -When nil, only the minibuffer will be available." - :group 'org-time - :type 'boolean) - -(defcustom org-calendar-follow-timestamp-change t - "Non-nil means, make the calendar window follow timestamp changes. -When a timestamp is modified and the calendar window is visible, it will be -moved to the new date." - :group 'org-time - :type 'boolean) - -(defcustom org-log-done nil - "When set, insert a (non-active) time stamp when TODO entry is marked DONE. -When the state of an entry is changed from nothing to TODO, remove a previous -closing date." - :group 'org-time - :type 'boolean) - -(defgroup org-agenda nil - "Options concerning agenda display Org-mode." - :tag "Org Agenda" - :group 'org) - -(defcustom org-agenda-files nil - "The files to be used for agenda display. -Entries may be added to this list with \\[org-agenda-file-to-front] and removed with -\\[org-remove-file]. You can also use customize to edit the list. - -If the value of the variable is not a list but a single file name, then -the list of agenda files is actually stored in that file, one agenda file -per line" - :group 'org-agenda - :type '(choice - (repeat :tag "List of files" file) - (file :tag "Store list in a file\n" :value "~/.agenda_files"))) - -(defcustom org-agenda-custom-commands '(("w" todo "WAITING")) - "Custom commands for the agenda. -These commands will be offered on the splash screen displayed by the -agenda dispatcher \\[org-agenda]. Each entry is a list of 3 items: - -key The key (a single char as a string) to be associated with the command. -type The command type, any of the following symbols: - todo Entries with a specific TODO keyword, in all agenda files. - tags Tags match in all agenda files. - todo-tree Sparse tree of specific TODO keyword in *current* file. - tags-tree Sparse tree with all tags matches in *current* file. - occur-tree Occur sparse tree for current file. -match What to search for: - - a single keyword for TODO keyword searches - - a tags match expression for tags searches - - a regular expression for occur searches" - :group 'org-agenda - :type '(repeat - (list (string :tag "Key") - (choice :tag "Type" - (const :tag "Tags search in all agenda files" tags) - (const :tag "TODO keyword search in all agenda files" todo) - (const :tag "Tags sparse tree in current buffer" tags-tree) - (const :tag "TODO keyword tree in current buffer" todo-tree) - (const :tag "Occur tree in current buffer" occur-tree)) - (string :tag "Match")))) - -(defcustom org-select-timeline-window t - "Non-nil means, after creating a timeline, move cursor into Timeline window. -When nil, cursor will remain in the current window." - :group 'org-agenda - :type 'boolean) - -(defcustom org-select-agenda-window t - "Non-nil means, after creating an agenda, move cursor into Agenda window. -When nil, cursor will remain in the current window." - :group 'org-agenda - :type 'boolean) - -(defcustom org-fit-agenda-window t - "Non-nil means, change window size of agenda to fit content." - :group 'org-agenda - :type 'boolean) - -(defcustom org-agenda-show-all-dates t - "Non-nil means, `org-agenda' shows every day in the selected range. -When nil, only the days which actually have entries are shown." - :group 'org-agenda - :type 'boolean) - -;; FIXME: First day of month works only for current month because it would -;; require a variable ndays treatment. -(defcustom org-agenda-start-on-weekday 1 - "Non-nil means, start the overview always on the specified weekday. -0 Denotes Sunday, 1 denotes Monday etc. -When nil, always start on the current day." - :group 'org-agenda - :type '(choice (const :tag "Today" nil) - (const :tag "First day of month" t) - (number :tag "Weekday No."))) - -(defcustom org-agenda-ndays 7 - "Number of days to include in overview display." - :group 'org-agenda - :type 'number) - -(defcustom org-agenda-include-all-todo t - "Non-nil means, the agenda will always contain all TODO entries. -When nil, date-less entries will only be shown if `org-agenda' is called -with a prefix argument. -When non-nil, the TODO entries will be listed at the top of the agenda, before -the entries for specific days." - :group 'org-agenda - :type 'boolean) - -(defcustom org-agenda-include-diary nil - "If non-nil, include in the agenda entries from the Emacs Calendar's diary." - :group 'org-agenda - :type 'boolean) - -(defcustom org-calendar-to-agenda-key [?c] - "The key to be installed in `calendar-mode-map' for switching to the agenda. -The command `org-calendar-goto-agenda' will be bound to this key. The -default is the character `c' because then `c' can be used to switch back and -forth between agenda and calendar." - :group 'org-agenda - :type 'sexp) - -(defcustom org-agenda-sorting-strategy '(time-up category-keep priority-down) - "Sorting structure for the agenda items of a single day. -This is a list of symbols which will be used in sequence to determine -if an entry should be listed before another entry. The following -symbols are recognized: - -time-up Put entries with time-of-day indications first, early first -time-down Put entries with time-of-day indications first, late first -category-keep Keep the default order of categories, corresponding to the - sequence in `org-agenda-files'. -category-up Sort alphabetically by category, A-Z. -category-down Sort alphabetically by category, Z-A. -priority-up Sort numerically by priority, high priority last. -priority-down Sort numerically by priority, high priority first. - -The different possibilities will be tried in sequence, and testing stops -if one comparison returns a \"not-equal\". For example, the default - '(time-up category-keep priority-down) -means: Pull out all entries having a specified time of day and sort them, -in order to make a time schedule for the current day the first thing in the -agenda listing for the day. Of the entries without a time indication, keep -the grouped in categories, don't sort the categories, but keep them in -the sequence given in `org-agenda-files'. Within each category sort by -priority. - -Leaving out `category-keep' would mean that items will be sorted across -categories by priority." - :group 'org-agenda - :type '(repeat - (choice - (const time-up) - (const time-down) - (const category-keep) - (const category-up) - (const category-down) - (const priority-up) - (const priority-down)))) - -(defcustom org-agenda-prefix-format " %-12:c%?-12t% s" - "Format specification for the prefix of items in the agenda buffer. -This format works similar to a printf format, with the following meaning: - - %c the category of the item, \"Diary\" for entries from the diary, or - as given by the CATEGORY keyword or derived from the file name. - %T the first tag of the item. - %t the time-of-day specification if one applies to the entry, in the - format HH:MM - %s Scheduling/Deadline information, a short string - -All specifiers work basically like the standard `%s' of printf, but may -contain two additional characters: A question mark just after the `%' and -a whitespace/punctuation character just before the final letter. - -If the first character after `%' is a question mark, the entire field -will only be included if the corresponding value applies to the -current entry. This is useful for fields which should have fixed -width when present, but zero width when absent. For example, -\"%?-12t\" will result in a 12 character time field if a time of the -day is specified, but will completely disappear in entries which do -not contain a time. - -If there is punctuation or whitespace character just before the final -format letter, this character will be appended to the field value if -the value is not empty. For example, the format \"%-12:c\" leads to -\"Diary: \" if the category is \"Diary\". If the category were be -empty, no additional colon would be interted. - -The default value of this option is \" %-12:c%?-12t% s\", meaning: -- Indent the line with two space characters -- Give the category in a 12 chars wide field, padded with whitespace on - the right (because of `-'). Append a colon if there is a category - (because of `:'). -- If there is a time-of-day, put it into a 12 chars wide field. If no - time, don't put in an empty field, just skip it (because of '?'). -- Finally, put the scheduling information and append a whitespace. - -As another example, if you don't want the time-of-day of entries in -the prefix, you could use: - - (setq org-agenda-prefix-format \" %-11:c% s\") - -See also the variables `org-agenda-remove-times-when-in-prefix' and -`org-agenda-remove-tags-when-in-prefix'." - :type 'string - :group 'org-agenda) - -(defcustom org-timeline-prefix-format " % s" - "Like `org-agenda-prefix-format', but for the timeline of a single file." - :type 'string - :group 'org-agenda) - -(defvar org-prefix-format-compiled nil - "The compiled version of the most recently used prefix format. -Depending on which command was used last, this may be the compiled version -of `org-agenda-prefix-format' or `org-timeline-prefix-format'.") - -(defcustom org-agenda-use-time-grid t - "Non-nil means, show a time grid in the agenda schedule. -A time grid is a set of lines for specific times (like every two hours between -8:00 and 20:00). The items scheduled for a day at specific times are -sorted in between these lines. -For details about when the grid will be shown, and what it will look like, see -the variable `org-agenda-time-grid'." - :group 'org-agenda - :type 'boolean) - -(defcustom org-agenda-time-grid - '((daily today require-timed) - "----------------" - (800 1000 1200 1400 1600 1800 2000)) - - "The settings for time grid for agenda display. -This is a list of three items. The first item is again a list. It contains -symbols specifying conditions when the grid should be displayed: - - daily if the agenda shows a single day - weekly if the agenda shows an entire week - today show grid on current date, independent of daily/weekly display - require-timed show grid only if at least on item has a time specification - -The second item is a string which will be places behing the grid time. - -The third item is a list of integers, indicating the times that should have -a grid line." - :group 'org-agenda - :type - '(list - (set :greedy t :tag "Grid Display Options" - (const :tag "Show grid in single day agenda display" daily) - (const :tag "Show grid in weekly agenda display" weekly) - (const :tag "Always show grid for today" today) - (const :tag "Show grid only if any timed entries are present" - require-timed) - (const :tag "Skip grid times already present in an entry" - remove-match)) - (string :tag "Grid String") - (repeat :tag "Grid Times" (integer :tag "Time")))) - -(defcustom org-agenda-remove-times-when-in-prefix t - "Non-nil means, remove duplicate time specifications in agenda items. -When the format `org-agenda-prefix-format' contains a `%t' specifier, a -time-of-day specification in a headline or diary entry is extracted and -placed into the prefix. If this option is non-nil, the original specification -\(a timestamp or -range, or just a plain time(range) specification like -11:30-4pm) will be removed for agenda display. This makes the agenda less -cluttered. -The option can be t or nil. It may also be the symbol `beg', indicating -that the time should only be removed what it is located at the beginning of -the headline/diary entry." - :group 'org-agenda - :type '(choice - (const :tag "Always" t) - (const :tag "Never" nil) - (const :tag "When at beginning of entry" beg))) - -(defcustom org-sort-agenda-notime-is-late t - "Non-nil means, items without time are considered late. -This is only relevant for sorting. When t, items which have no explicit -time like 15:30 will be considered as 24:01, i.e. later than any items which -do have a time. When nil, the default time is before 0:00. You can use this -option to decide if the schedule for today should come before or after timeless -agenda entries." - :group 'org-agenda - :type 'boolean) - -(defcustom org-agenda-remove-tags-when-in-prefix nil - "Non-nil means, the tags from copy of headline in agenda. -When this is the symbol `prefix', only remove tags when -`org-agenda-prefix-format' contains a `%T' specifier." - :group 'org-agenda - :type '(choice - (const :tag "Always" t) - (const :tag "Never" nil) - (const :tag "When prefix format contains %T" prefix))) - (defgroup org-structure nil - "Options concerning structure editing in Org-mode." + "Options concerning the general structure of Org-mode files." :tag "Org Structure" :group 'org) -(defcustom org-cycle-include-plain-lists nil - "Non-nil means, include plain lists into visibility cycling. -This means that during cycling, plain list items will *temporarily* be -interpreted as outline headlines with a level given by 1000+i where i is the -indentation of the bullet. In all other operations, plain list items are -not seen as headlines. For example, you cannot assign a TODO keyword to -such an item." - :group 'org-structure - :type 'boolean) +(defgroup org-cycle nil + "Options concerning visibility cycling in Org-mode." + :tag "Org Cycle" + :group 'org-structure) (defcustom org-cycle-emulate-tab t "Where should `org-cycle' emulate TAB. nil Never white Only in completely white lines t Everywhere except in headlines" - :group 'org-structure + :group 'org-cycle :type '(choice (const :tag "Never" nil) (const :tag "Only in completely white lines" white) (const :tag "Everywhere except in headlines" t) @@ -813,20 +372,59 @@ the new state that was set by the most recent `org-cycle' command. The argument is a symbol. After a global state change, it can have the values `overview', `content', or `all'. After a local state change, it can have the values `folded', `children', or `subtree'." - :group 'org-structure + :group 'org-cycle :type 'hook) +(defgroup org-edit-structure nil + "Options concerning structure editing in Org-mode." + :tag "Org Edit Structure" + :group 'org-structure) + +(defcustom org-odd-levels-only nil + "Non-nil means, skip even levels and only use odd levels for the outline. +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." + :group 'org-edit-structure + :group 'org-font-lock + :type 'boolean) + +(defcustom org-adapt-indentation t + "Non-nil means, adapt indentation when promoting and demoting. +When this is set and the *entire* text in an entry is indented, the +indentation is increased by one space in a demotion command, and +decreased by one in a promotion command. If any line in the entry +body starts at column 0, indentation is not changed at all." + :group 'org-edit-structure + :type 'boolean) + +;; FIXME: in the wrong group, but where would it fit???? +(defcustom org-enable-fixed-width-editor t + "Non-nil means, lines starting with \":\" are treated as fixed-width. +This currently only means, they are never auto-wrapped. +When nil, such lines will be treated like ordinary lines. +See also the QUOTE keyword." + :group 'org-edit-structure + :type 'boolean) + +(defgroup org-sparse-trees nil + "Options concerning sparse trees in Org-mode." + :tag "Org Sparse Trees" + :group 'org-structure) + (defcustom org-highlight-sparse-tree-matches t "Non-nil means, highlight all matches that define a sparse tree. The highlights will automatically disappear the next time the buffer is changed by an edit command." - :group 'org-structure + :group 'org-sparse-trees :type 'boolean) (defcustom org-show-hierarchy-above t "Non-nil means, show full hierarchy when showing a spot in the tree. Turning this off makes sparse trees more compact, but also less clear." - :group 'org-structure + :group 'org-sparse-trees :type 'boolean) (defcustom org-show-following-heading t @@ -836,43 +434,39 @@ follows the match, even if they do not match the regexp. This makes it easier to edit directly inside the sparse tree. However, if you use `org-occur' mainly as an overview, the following headlines are unnecessary clutter." - :group 'org-structure + :group 'org-sparse-trees :type 'boolean) (defcustom org-occur-hook '(org-first-headline-recenter) "Hook that is run after `org-occur' has constructed a sparse tree. This can be used to recenter the window to show as much of the structure as possible." - :group 'org-structure + :group 'org-sparse-trees :type 'hook) -(defcustom org-odd-levels-only nil - "Non-nil means, skip even levels and only use odd levels for the outline. -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." - :group 'org-structure - :group 'org-font-lock - :type 'boolean) +(defgroup org-plain-lists nil + "Options concerning plain lists in Org-mode." + :tag "Org Plain lists" + :group 'org-structure) -(defcustom org-adapt-indentation t - "Non-nil means, adapt indentation when promoting and demoting. -When this is set and the *entire* text in an entry is indented, the -indentation is increased by one space in a demotion command, and -decreased by one in a promotion command. If any line in the entry -body starts at column 0, indentation is not changed at all." - :group 'org-structure +(defcustom org-cycle-include-plain-lists nil + "Non-nil means, include plain lists into visibility cycling. +This means that during cycling, plain list items will *temporarily* be +interpreted as outline headlines with a level given by 1000+i where i is the +indentation of the bullet. In all other operations, plain list items are +not seen as headlines. For example, you cannot assign a TODO keyword to +such an item." + :group 'org-plain-lists :type 'boolean) + (defcustom org-plain-list-ordered-item-terminator t "The character that makes a line with leading number an ordered list item. Valid values are ?. and ?\). To get both terminators, use t. While ?. may look nicer, it creates the danger that a line with leading number may be incorrectly interpreted as an item. ?\) therefore is the safe choice." - :group 'org-structure + :group 'org-plain-lists :type '(choice (const :tag "dot like in \"2.\"" ?.) (const :tag "paren like in \"2)\"" ?\)) (const :tab "both" t))) @@ -882,22 +476,13 @@ the safe choice." Renumbering happens when the sequence have been changed with \\[org-shiftmetaup] or \\[org-shiftmetadown]. After other editing commands, use \\[org-ctrl-c-ctrl-c] to trigger renumbering." - :group 'org-structure - :type 'boolean) - -(defcustom org-enable-fixed-width-editor t - "Non-nil means, lines starting with \":\" are treated as fixed-width. -This currently only means, they are never auto-wrapped. -When nil, such lines will be treated like ordinary lines. -See also the QUOTE keyword." - :group 'org-structure + :group 'org-plain-lists :type 'boolean) - (defgroup org-archive nil "Options concerning archiving in Org-mode." :tag "Org Archive" - :group 'org) + :group 'org-structure) (defcustom org-archive-location "%s_archive::" "The location where subtrees should be archived. @@ -948,54 +533,227 @@ first line, so it is probably best to use this in combinations with :group 'org-archive :type 'boolean) -(defgroup org-tags nil - "Options concerning startup of Org-mode." - :tag "Org Tags" +(defgroup org-table nil + "Options concerning tables in Org-mode." + :tag "Org Table" :group 'org) -(defcustom org-tags-column 48 - "The column to which tags should be indented in a headline. -If this number is positive, it specifies the column. If it is negative, -it means that the tags should be flushright to that column. For example, --79 works well for a normal 80 character screen." - :group 'org-tags - :type 'integer) +(defcustom org-enable-table-editor 'optimized + "Non-nil means, lines starting with \"|\" are handled by the table editor. +When nil, such lines will be treated like ordinary lines. -(defcustom org-auto-align-tags t - "Non-nil means, realign tags after pro/demotion of TODO state change. -These operations change the length of a headline and therefore shift -the tags around. With this options turned on, after each such operation -the tags are again aligned to `org-tags-column'." - :group 'org-tags +When equal to the symbol `optimized', the table editor will be optimized to +do the following: +- Use automatic overwrite mode in front of whitespace in table fields. + This make the structure of the table stay in tact as long as the edited + field does not exceed the column width. +- Minimize the number of realigns. Normally, the table is aligned each time + TAB or RET are pressed to move to another field. With optimization this + happens only if changes to a field might have changed the column width. +Optimization requires replacing the functions `self-insert-command', +`delete-char', and `backward-delete-char' in Org-mode buffers, with a +slight (in fact: unnoticeable) speed impact for normal typing. Org-mode is +very good at guessing when a re-align will be necessary, but you can always +force one with \\[org-ctrl-c-ctrl-c]. + +If you would like to use the optimized version in Org-mode, but the +un-optimized version in OrgTbl-mode, see the variable `orgtbl-optimized'. + +This variable can be used to turn on and off the table editor during a session, +but in order to toggle optimization, a restart is required. + +See also the variable `org-table-auto-blank-field'." + :group 'org-table + :type '(choice + (const :tag "off" nil) + (const :tag "on" t) + (const :tag "on, optimized" optimized))) + +(defcustom orgtbl-optimized (eq org-enable-table-editor 'optimized) + "Non-nil means, use the optimized table editor version for `orgtbl-mode'. +In the optimized version, the table editor takes over all simple keys that +normally just insert a character. In tables, the characters are inserted +in a way to minimize disturbing the table structure (i.e. in overwrite mode +for empty fields). Outside tables, the correct binding of the keys is +restored. + +The default for this option is t if the optimized version is also used in +Org-mode. See the variable `org-enable-table-editor' for details. Changing +this variable requires a restart of Emacs to become effective." + :group 'org-table :type 'boolean) -(defcustom org-use-tag-inheritance t - "Non-nil means, tags in levels apply also for sublevels. -When nil, only the tags directly given in a specific line apply there. -If you turn off this option, you very likely want to turn on the -companion option `org-tags-match-list-sublevels'." - :group 'org-tags +(defgroup org-table-settings nil + "Settings for tables in Org-mode." + :tag "Org Table Settings" + :group 'org-table) + +(defcustom org-table-default-size "5x2" + "The default size for newly created tables, Columns x Rows." + :group 'org-table-settings + :type 'string) + +(defcustom org-table-spaces-around-separators '(1 . 1) + "The number of spaces to be placed before and after separators." + :group 'org-table-settings + :type '(cons (number :tag "Before \"|\"") (number :tag " After \"|\""))) + +(defcustom org-table-spaces-around-invisible-separators '(1 . 2) + "The number of spaces to be placed before and after separators. +This option applies when the column separators have been made invisible." + :group 'org-table-settings + :type '(cons (number :tag "Before \"|\"") (number :tag " After \"|\""))) + +(defcustom org-table-number-regexp "^[<>]?[-+^.0-9]*[0-9][-+^.0-9eEdDx()%]*$" + "Regular expression for recognizing numbers in table columns. +If a table column contains mostly numbers, it will be aligned to the +right. If not, it will be aligned to the left. + +The default value of this option is a regular expression which allows +anything which looks remotely like a number as used in scientific +context. For example, all of the following will be considered a +number: + 12 12.2 2.4e-08 2x10^12 4.034+-0.02 2.7(10) >3.5 + +Other options offered by the customize interface are more restrictive." + :group 'org-table-settings + :type '(choice + (const :tag "Positive Integers" + "^[0-9]+$") + (const :tag "Integers" + "^[-+]?[0-9]+$") + (const :tag "Floating Point Numbers" + "^[-+]?\\([0-9]*\\.[0-9]+\\|[0-9]+\\.[0-9]*\\)$") + (const :tag "Floating Point Number or Integer" + "^[-+]?\\([0-9]*\\.[0-9]+\\|[0-9]+\\.?[0-9]*\\)$") + (const :tag "Exponential, Floating point, Integer" + "^[-+]?[0-9.]+\\([eEdD][-+0-9]+\\)?$") + (const :tag "Very General Number-Like" + "^[<>]?[-+^.0-9]*[0-9][-+^.0-9eEdDx()%]*$") + (string :tag "Regexp:"))) + +(defcustom org-table-number-fraction 0.5 + "Fraction of numbers in a column required to make the column align right. +In a column all non-white fields are considered. If at least this +fraction of fields is matched by `org-table-number-fraction', +alignment to the right border applies." + :group 'org-table-settings + :type 'number) + +(defgroup org-table-editing nil + "Bahavior of tables during editing in Org-mode." + :tag "Org Table Editing" + :group 'org-table) + +(defcustom org-table-automatic-realign t + "Non-nil means, automatically re-align table when pressing TAB or RETURN. +When nil, aligning is only done with \\[org-table-align], or after column +removal/insertion." + :group 'org-table-editing :type 'boolean) -(defcustom org-tags-match-list-sublevels nil - "Non-nil means list also sublevels of headlines matching tag search. -Because of tag inheritance (see variable `org-use-tag-inheritance'), -the sublevels of a headline matching a tag search often also match -the same search. Listing all of them can create very long lists. -Setting this variable to nil causes subtrees to be skipped. -This option is off by default, because inheritance in on. If you turn -inheritance off, you very likely want to turn this option on. +(defcustom org-table-limit-column-width t + "Non-nil means, allow to limit the width of table columns with <N> fields." + :group 'org-table-editing + :type 'boolean) -As a special case, if the tag search is restricted to TODO items, the -value of this variable is ignored and sublevels are always checked, to -make sure all corresponding TODO items find their way into the list." - :group 'org-tags +(defcustom org-table-auto-blank-field t + "Non-nil means, automatically blank table field when starting to type into it. +This only happens when typing immediately after a field motion +command (TAB, S-TAB or RET). +Only relevant when `org-enable-table-editor' is equal to `optimized'." + :group 'org-table-editing + :type 'boolean) + +(defcustom org-table-tab-jumps-over-hlines t + "Non-nil means, tab in the last column of a table with jump over a hline. +If a horizontal separator line is following the current line, +`org-table-next-field' can either create a new row before that line, or jump +over the line. When this option is nil, a new line will be created before +this line." + :group 'org-table-editing + :type 'boolean) + +(defcustom org-table-tab-recognizes-table.el t + "Non-nil means, TAB will automatically notice a table.el table. +When it sees such a table, it moves point into it and - if necessary - +calls `table-recognize-table'." + :group 'org-table-editing + :type 'boolean) + +(defgroup org-table-calculation nil + "Options concerning tables in Org-mode." + :tag "Org Table Calculation" + :group 'org-table) + +(defcustom org-table-copy-increment t + "Non-nil means, increment when copying current field with \\[org-table-copy-down]." + :group 'org-table-calculation + :type 'boolean) + +(defcustom org-calc-default-modes + '(calc-internal-prec 12 + calc-float-format (float 5) + calc-angle-mode deg + calc-prefer-frac nil + calc-symbolic-mode nil + calc-date-format (YYYY "-" MM "-" DD " " Www (" " HH ":" mm)) + calc-display-working-message t + ) + "List with Calc mode settings for use in calc-eval for table formulas. +The list must contain alternating symbols (Calc modes variables and values). +Don't remove any of the default settings, just change the values. Org-mode +relies on the variables to be present in the list." + :group 'org-table-calculation + :type 'plist) + +(defcustom org-table-formula-evaluate-inline t + "Non-nil means, TAB and RET evaluate a formula in current table field. +If the current field starts with an equal sign, it is assumed to be a formula +which should be evaluated as described in the manual and in the documentation +string of the command `org-table-eval-formula'. This feature requires the +Emacs calc package. +When this variable is nil, formula calculation is only available through +the command \\[org-table-eval-formula]." + :group 'org-table-calculation :type 'boolean) -(defvar org-tags-history nil - "History of minibuffer reads for tags.") -(defvar org-last-tags-completion-table nil - "The last used completion table for tags.") + +(defcustom org-table-formula-use-constants t + "Non-nil means, interpret constants in formulas in tables. +A constant looks like `$c' or `$Grav' and will be replaced before evaluation +by the value given in `org-table-formula-constants', or by a value obtained +from the `constants.el' package." + :group 'org-table-calculation + :type 'boolean) + +(defcustom org-table-formula-constants nil + "Alist with constant names and values, for use in table formulas. +The car of each element is a name of a constant, without the `$' before it. +The cdr is the value as a string. For example, if you'd like to use the +speed of light in a formula, you would configure + + (setq org-table-formula-constants '((\"c\" . \"299792458.\"))) + +and then use it in an equation like `$1*$c'." + :group 'org-table-calculation + :type '(repeat + (cons (string :tag "name") + (string :tag "value")))) + +(defcustom org-table-formula-numbers-only nil + "Non-nil means, calculate only with numbers in table formulas. +Then all input fields will be converted to a number, and the result +must also be a number. When nil, calc's full potential is available +in table calculations, including symbolics etc." + :group 'org-table-calculation + :type 'boolean) + +(defcustom org-table-allow-automatic-line-recalculation t + "Non-nil means, lines marked with |#| or |*| will be recomputed automatically. +Automatically means, when TAB or RET or C-c C-c are pressed in the line." + :group 'org-table-calculation + :type 'boolean) (defgroup org-link nil "Options concerning links in Org-mode." @@ -1010,36 +768,23 @@ 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." +(defcustom org-link-style 'bracket + "The style of links to be inserted with \\[org-insert-link]. +Possible values are: +bracket [[link][description]]. This is recommended +plain Description \\n link. The old way, no longer recommended." :group 'org-link - :type 'boolean) - -(defcustom org-return-follows-link nil - "Non-nil means, on links RET will follow the link. -Needs to be set before org.el is loaded." - :group 'org-link - :type 'boolean) - -(defcustom org-mark-ring-length 4 - "Number of different positions to be recorded in the ring -Changing this requires a restart of Emacs to work correctly." - :group 'org-link - :type 'interger) + :type '(choice + (const :tag "Bracket (recommended)" bracket) + (const :tag "Plain (no longer recommended)" plain))) -(defcustom org-link-format "<%s>" +(defcustom org-link-format "%s" "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 -recommend an additional URL: prefix, so the format would be \"<URL:%s>\"." +The recommended value is just \"%s\", since links will be protected by +enclosing them in double brackets. If you prefer plain links (see variable +`org-link-style'), \"<%s>\" is useful. Some people also recommend an +additional URL: prefix, so the format would be \"<URL:%s>\"." :group 'org-link :type '(choice (const :tag "\"%s\" (e.g. http://www.there.com)" "%s") @@ -1047,13 +792,17 @@ recommend an additional URL: prefix, so the format would be \"<URL:%s>\"." (const :tag "\"<URL:%s>\" (e.g. <URL:http://www.there.com>)" "<URL:%s>") (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. -Note that in tables, a link never extends accross fields, so in a table -it is always possible to put several links into a line. -Changing this variable requires a restart of Emacs of become effective." +(defvaralias 'org-allow-space-in-links 'org-allow-space-in-plain-links) + +(defcustom org-allow-space-in-plain-links nil + "Non-nil means, space characters may be part of a plain text link. +Space characters are no problem in links enclosed by double square brackets. +But in plain text, if space is allowed, org-mode does not know where to +terminate the link and reads until the end of the line. +This variable exists only to force compatibility with old org-mode files. +I discourage setting this to t, and support for this may not be available +in the future. +Changing this requires a restart of Emacs to become effective." :group 'org-link :type 'boolean) @@ -1071,6 +820,11 @@ Changing this requires restart of Emacs to become effective." :group 'org-link :type 'boolean) +(defgroup org-link-store nil + "Options concerning storing links in Org-mode" + :tag "Org Store Link" + :group 'org-link) + (defcustom org-context-in-file-links t "Non-nil means, file links from `org-store-link' contain context. A search string will be added to the file name with :: as separator and @@ -1078,14 +832,14 @@ used to find the context when the link is activated by the command `org-open-at-point'. Using a prefix arg to the command \\[org-store-link] (`org-store-link') negates this setting for the duration of the command." - :group 'org-link + :group 'org-link-store :type 'boolean) (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. CamelCase is deprecated, and support for it may be dropped in the future." - :group 'org-link + :group 'org-link-store :type 'boolean) (defcustom org-keep-stored-link-after-insertion nil @@ -1098,9 +852,40 @@ Org-mode file (offering completion for all stored links). When this option is nil, every link which has been inserted once using \\[org-insert-link] will be removed from the list, to make completing the unused links more efficient." - :group 'org-link + :group 'org-link-store + :type 'boolean) + +(defcustom org-usenet-links-prefer-google nil + "Non-nil means, `org-store-link' will create web links to Google groups. +When nil, Gnus will be used for such links. +Using a prefix arg to the command \\[org-store-link] (`org-store-link') +negates this setting for the duration of the command." + :group 'org-link-store + :type 'boolean) + +(defgroup org-link-follow nil + "Options concerning following links in Org-mode" + :tag "Org Follow Link" + :group 'org-link) + +(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." + :group 'org-link-follow + :type 'boolean) + +(defcustom org-return-follows-link nil + "Non-nil means, on links RET will follow the link. +Needs to be set before org.el is loaded." + :group 'org-link-follow :type 'boolean) +(defcustom org-mark-ring-length 4 + "Number of different positions to be recorded in the ring +Changing this requires a restart of Emacs to work correctly." + :group 'org-link-follow + :type 'interger) + (defcustom org-link-frame-setup '((vm . vm-visit-folder-other-frame) (gnus . gnus-other-frame) @@ -1122,7 +907,7 @@ For FILE, use any of For the calendar, use the variable `calendar-setup'. For BBDB, it is currently only possible to display the matches in another window." - :group 'org-link + :group 'org-link-follow :type '(list (cons (const vm) (choice @@ -1139,24 +924,16 @@ another window." (const find-file-other-window) (const find-file-other-frame))))) -(defcustom org-usenet-links-prefer-google nil - "Non-nil means, `org-store-link' will create web links to Google groups. -When nil, Gnus will be used for such links. -Using a prefix arg to the command \\[org-store-link] (`org-store-link') -negates this setting for the duration of the command." - :group 'org-link - :type 'boolean) - (defcustom org-open-non-existing-files nil "Non-nil means, `org-open-file' will open non-existing file. When nil, an error will be generated." - :group 'org-link + :group 'org-link-follow :type 'boolean) (defcustom org-confirm-shell-links t "Non-nil means, ask for confirmation before executing shell links. The default is true, to keep new users from shooting into their own foot." - :group 'org-link + :group 'org-link-follow :type 'boolean) (defconst org-file-apps-defaults-gnu @@ -1206,7 +983,7 @@ For more examples, see the system specific constants `org-file-apps-defaults-macosx' `org-file-apps-defaults-windowsnt' `org-file-apps-defaults-gnu'." - :group 'org-link + :group 'org-link-follow :type '(repeat (cons (choice :value "" (string :tag "Extension") @@ -1223,7 +1000,7 @@ For more examples, see the system specific constants 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 supported by MH-E, but will be slow with pick." - :group 'org-link + :group 'org-link-follow :type 'boolean) (defgroup org-remember nil @@ -1285,220 +1062,502 @@ When nil, new notes will be filed to the end of a file or entry." (repeat :tag "By file name regexp" (cons regexp boolean)))) -(defgroup org-table nil - "Options concerning tables in Org-mode." - :tag "Org Table" +(defgroup org-todo nil + "Options concerning TODO items in Org-mode." + :tag "Org TODO" :group 'org) -(defcustom org-enable-table-editor 'optimized - "Non-nil means, lines starting with \"|\" are handled by the table editor. -When nil, such lines will be treated like ordinary lines. +(defcustom org-todo-keywords '("TODO" "DONE") + "List of TODO entry keywords. +\\<org-mode-map>By default, this is '(\"TODO\" \"DONE\"). The last entry in the list is +considered to mean that the entry is \"done\". All the other mean that +action is required, and will make the entry show up in todo lists, diaries +etc. +The command \\[org-todo] cycles an entry through these states, and an +additional state where no keyword is present. For details about this +cycling, see also the variable `org-todo-interpretation' +Changes become only effective after restarting Emacs." + :group 'org-todo + :group 'org-keywords + :type '(repeat (string :tag "Keyword"))) -When equal to the symbol `optimized', the table editor will be optimized to -do the following: -- Use automatic overwrite mode in front of whitespace in table fields. - This make the structure of the table stay in tact as long as the edited - field does not exceed the column width. -- Minimize the number of realigns. Normally, the table is aligned each time - TAB or RET are pressed to move to another field. With optimization this - happens only if changes to a field might have changed the column width. -Optimization requires replacing the functions `self-insert-command', -`delete-char', and `backward-delete-char' in Org-mode buffers, with a -slight (in fact: unnoticeable) speed impact for normal typing. Org-mode is -very good at guessing when a re-align will be necessary, but you can always -force one with \\[org-ctrl-c-ctrl-c]. +(defcustom org-todo-interpretation 'sequence + "Controls how TODO keywords are interpreted. +\\<org-mode-map>Possible values are `sequence' and `type'. +This variable is only relevant if `org-todo-keywords' contains more than two +states. There are two ways how these keywords can be used: -If you would like to use the optimized version in Org-mode, but the -un-optimized version in OrgTbl-mode, see the variable `orgtbl-optimized'. +- As a sequence in the process of working on a TODO item, for example + (setq org-todo-keywords '(\"TODO\" \"STARTED\" \"VERIFY\" \"DONE\") + org-todo-interpretation 'sequence) -This variable can be used to turn on and off the table editor during a session, -but in order to toggle optimization, a restart is required. +- As different types of TODO items, for example + (setq org-todo-keywords '(\"URGENT\" \"RELAXED\" \"REMIND\" \"FOR_TOM\" \"DONE\") + org-todo-interpretation 'type) -See also the variable `org-table-auto-blank-field'." - :group 'org-table - :type '(choice - (const :tag "off" nil) - (const :tag "on" t) - (const :tag "on, optimized" optimized))) +When the states are interpreted as a sequence, \\[org-todo] always cycles +to the next state, in order to walk through all different states. So with +\\[org-todo], you turn an empty entry into the state TODO. When you started +working on the item, you use \\[org-todo] again to switch it to \"STARTED\", +later to VERIFY and finally to DONE. -;; FIXME: We could have a third option which makes it jump only over the first -;; hline in a table. -(defcustom org-table-tab-jumps-over-hlines t - "Non-nil means, tab in the last column of a table with jump over a hline. -If a horizontal separator line is following the current line, -`org-table-next-field' can either create a new row before that line, or jump -over the line. When this option is nil, a new line will be created before -this line." - :group 'org-table +When the states are interpreted as types, \\[org-todo] still cycles through +when it is called several times in direct succession, in order to initially +select the type. However, if not called immediately after a previous +\\[org-todo], it switches from each type directly to DONE. So with the +above example, you could use `\\[org-todo] \\[org-todo]' to label an entry +RELAXED. If you later return to this entry and press \\[org-todo] again, +RELAXED will not be changed REMIND, but directly to DONE. + +You can create a large number of types. To initially select a +type, it is then best to use \\[universal-argument] \\[org-todo] in order to specify the +type with completion. Of course, you can also type the keyword +directly into the buffer. M-TAB completes TODO keywords at the +beginning of a headline." + :group 'org-todo + :group 'org-keywords + :type '(choice (const sequence) + (const type))) + +(defcustom org-after-todo-state-change-hook nil + "Hook which is run after the state of a TODO item was changed. +The new state (a string with a TODO keyword, or nil) is available in the +Lisp variable `state'." + :group 'org-todo + :type 'hook) + +(defcustom org-log-done nil + "When set, insert a (non-active) time stamp when TODO entry is marked DONE. +When the state of an entry is changed from nothing to TODO, remove a previous +closing date." + :group 'org-todo :type 'boolean) -(defcustom org-table-auto-blank-field t - "Non-nil means, automatically blank table field when starting to type into it. -This only happens when typing immediately after a field motion -command (TAB, S-TAB or RET). -Only relevant when `org-enable-table-editor' is equal to `optimized'." - :group 'org-table +;; FIXME: Correct to put this into the TODO group??? +(defgroup org-priorities nil + "Keywords in Org-mode." + :tag "Org Priorities" + :group 'org-todo) + +(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-priorities + :type 'character) + +(defcustom org-lowest-priority ?C + "The lowest priority of TODO items. A character like ?A, ?B etc." + :group 'org-priorities + :type 'character) + +;; FIXME: move to agenda????? +(defvar org-category nil + "Variable used by org files to set a category for agenda display. +Such files should use a file variable to set it, for example + + -*- mode: org; org-category: \"ELisp\" + +or contain a special line + +#+CATEGORY: ELisp + +If the file does not specify a category, then file's base name +is used instead.") +(make-variable-buffer-local 'org-category) + +(defgroup org-time nil + "Options concerning time stamps and deadlines in Org-mode." + :tag "Org Time" + :group 'org) + +(defconst org-time-stamp-formats '("<%Y-%m-%d %a>" . "<%Y-%m-%d %a %H:%M>") + "Formats for `format-time-string' which are used for time stamps. +It is not recommended to change this constant.") + +(defcustom org-time-stamp-rounding-minutes 0 + "Number of minutes to round time stamps to upon insertion. +When zero, insert the time unmodified. Useful rounding numbers +should be factors of 60, so for example 5, 10, 15. +When this is not zero, you can still force an exact time-stamp by using +a double prefix argument to a time-stamp command like `C-c .' or `C-c !'." + :group 'org-time + :type 'integer) + +(defcustom org-deadline-warning-days 30 + "No. of days before expiration during which a deadline becomes active. +This variable governs the display in the org file." + :group 'org-time + :type 'number) + +(defcustom org-popup-calendar-for-date-prompt t + "Non-nil means, pop up a calendar when prompting for a date. +In the calendar, the date can be selected with mouse-1. However, the +minibuffer will also be active, and you can simply enter the date as well. +When nil, only the minibuffer will be available." + :group 'org-time :type 'boolean) -(defcustom org-table-default-size "5x2" - "The default size for newly created tables, Columns x Rows." - :group 'org-table - :type 'string) +(defcustom org-calendar-follow-timestamp-change t + "Non-nil means, make the calendar window follow timestamp changes. +When a timestamp is modified and the calendar window is visible, it will be +moved to the new date." + :group 'org-time + :type 'boolean) -(defcustom org-table-automatic-realign t - "Non-nil means, automatically re-align table when pressing TAB or RETURN. -When nil, aligning is only done with \\[org-table-align], or after column -removal/insertion." - :group 'org-table +(defgroup org-tags nil + "Options concerning startup of Org-mode." + :tag "Org Tags" + :group 'org) + +(defcustom org-tags-column 48 + "The column to which tags should be indented in a headline. +If this number is positive, it specifies the column. If it is negative, +it means that the tags should be flushright to that column. For example, +-79 works well for a normal 80 character screen." + :group 'org-tags + :type 'integer) + +(defcustom org-auto-align-tags t + "Non-nil means, realign tags after pro/demotion of TODO state change. +These operations change the length of a headline and therefore shift +the tags around. With this options turned on, after each such operation +the tags are again aligned to `org-tags-column'." + :group 'org-tags :type 'boolean) -(defcustom org-table-spaces-around-separators '(1 . 1) - "The number of spaces to be placed before and after separators." - :group 'org-table - :type '(cons (number :tag "Before \"|\"") (number :tag " After \"|\""))) +(defcustom org-use-tag-inheritance t + "Non-nil means, tags in levels apply also for sublevels. +When nil, only the tags directly given in a specific line apply there. +If you turn off this option, you very likely want to turn on the +companion option `org-tags-match-list-sublevels'." + :group 'org-tags + :type 'boolean) -(defcustom org-table-spaces-around-invisible-separators '(1 . 2) - "The number of spaces to be placed before and after separators. -This option applies when the column separators have been made invisible." - :group 'org-table - :type '(cons (number :tag "Before \"|\"") (number :tag " After \"|\""))) +(defcustom org-tags-match-list-sublevels nil + "Non-nil means list also sublevels of headlines matching tag search. +Because of tag inheritance (see variable `org-use-tag-inheritance'), +the sublevels of a headline matching a tag search often also match +the same search. Listing all of them can create very long lists. +Setting this variable to nil causes subtrees to be skipped. +This option is off by default, because inheritance in on. If you turn +inheritance off, you very likely want to turn this option on. -(defcustom org-table-number-regexp "^[<>]?[-+^.0-9]*[0-9][-+^.0-9eEdDx()%]*$" - "Regular expression for recognizing numbers in table columns. -If a table column contains mostly numbers, it will be aligned to the -right. If not, it will be aligned to the left. +As a special case, if the tag search is restricted to TODO items, the +value of this variable is ignored and sublevels are always checked, to +make sure all corresponding TODO items find their way into the list." + :group 'org-tags + :type 'boolean) -The default value of this option is a regular expression which allows -anything which looks remotely like a number as used in scientific -context. For example, all of the following will be considered a -number: - 12 12.2 2.4e-08 2x10^12 4.034+-0.02 2.7(10) >3.5 +(defvar org-tags-history nil + "History of minibuffer reads for tags.") +(defvar org-last-tags-completion-table nil + "The last used completion table for tags.") -Other options offered by the customize interface are more restrictive." - :group 'org-table +(defgroup org-agenda nil + "Options concerning agenda display Org-mode." + :tag "Org Agenda" + :group 'org) + +(defcustom org-agenda-files nil + "The files to be used for agenda display. +Entries may be added to this list with \\[org-agenda-file-to-front] and removed with +\\[org-remove-file]. You can also use customize to edit the list. + +If the value of the variable is not a list but a single file name, then +the list of agenda files is actually stored in that file, one agenda file +per line" + :group 'org-agenda :type '(choice - (const :tag "Positive Integers" - "^[0-9]+$") - (const :tag "Integers" - "^[-+]?[0-9]+$") - (const :tag "Floating Point Numbers" - "^[-+]?\\([0-9]*\\.[0-9]+\\|[0-9]+\\.[0-9]*\\)$") - (const :tag "Floating Point Number or Integer" - "^[-+]?\\([0-9]*\\.[0-9]+\\|[0-9]+\\.?[0-9]*\\)$") - (const :tag "Exponential, Floating point, Integer" - "^[-+]?[0-9.]+\\([eEdD][-+0-9]+\\)?$") - (const :tag "Very General Number-Like" - "^[<>]?[-+^.0-9]*[0-9][-+^.0-9eEdDx()%]*$") - (string :tag "Regexp:"))) + (repeat :tag "List of files" file) + (file :tag "Store list in a file\n" :value "~/.agenda_files"))) -(defcustom org-table-number-fraction 0.5 - "Fraction of numbers in a column required to make the column align right. -In a column all non-white fields are considered. If at least this -fraction of fields is matched by `org-table-number-fraction', -alignment to the right border applies." - :group 'org-table - :type 'number) +(defcustom org-agenda-custom-commands '(("w" todo "WAITING")) + "Custom commands for the agenda. +These commands will be offered on the splash screen displayed by the +agenda dispatcher \\[org-agenda]. Each entry is a list of 3 items: -(defcustom org-export-highlight-first-table-line t - "Non-nil means, highlight the first table line. -In HTML export, this means use <th> instead of <td>. -In tables created with table.el, this applies to the first table line. -In Org-mode tables, all lines before the first horizontal separator -line will be formatted with <th> tags." - :group 'org-table +key The key (a single char as a string) to be associated with the command. +type The command type, any of the following symbols: + todo Entries with a specific TODO keyword, in all agenda files. + tags Tags match in all agenda files. + todo-tree Sparse tree of specific TODO keyword in *current* file. + tags-tree Sparse tree with all tags matches in *current* file. + occur-tree Occur sparse tree for current file. +match What to search for: + - a single keyword for TODO keyword searches + - a tags match expression for tags searches + - a regular expression for occur searches" + :group 'org-agenda + :type '(repeat + (list (string :tag "Key") + (choice :tag "Type" + (const :tag "Tags search in all agenda files" tags) + (const :tag "TODO keyword search in all agenda files" todo) + (const :tag "Tags sparse tree in current buffer" tags-tree) + (const :tag "TODO keyword tree in current buffer" todo-tree) + (const :tag "Occur tree in current buffer" occur-tree)) + (string :tag "Match")))) + +(defcustom org-agenda-include-all-todo t + "Non-nil means, the agenda will always contain all TODO entries. +When nil, date-less entries will only be shown if `org-agenda' is called +with a prefix argument. +When non-nil, the TODO entries will be listed at the top of the agenda, before +the entries for specific days." + :group 'org-agenda :type 'boolean) -(defcustom org-table-tab-recognizes-table.el t - "Non-nil means, TAB will automatically notice a table.el table. -When it sees such a table, it moves point into it and - if necessary - -calls `table-recognize-table'." - :group 'org-table +(defcustom org-agenda-include-diary nil + "If non-nil, include in the agenda entries from the Emacs Calendar's diary." + :group 'org-agenda :type 'boolean) -(defcustom org-table-limit-column-width t - "Non-nil means, allow to limit the width of table columns with <N> fields." - :group 'org-table +(defcustom org-calendar-to-agenda-key [?c] + "The key to be installed in `calendar-mode-map' for switching to the agenda. +The command `org-calendar-goto-agenda' will be bound to this key. The +default is the character `c' because then `c' can be used to switch back and +forth between agenda and calendar." + :group 'org-agenda + :type 'sexp) + +(defgroup org-agenda-window-setup nil + "Options concerning setting up the Agenda window in Org Mode." + :tag "Org Agenda Window Setup" + :group 'org-agenda) + +(defcustom org-select-timeline-window t + "Non-nil means, after creating a timeline, move cursor into Timeline window. +When nil, cursor will remain in the current window." + :group 'org-agenda-window-setup :type 'boolean) -(defgroup org-table-calculation nil - "Options concerning tables in Org-mode." - :tag "Org Table Calculation" - :group 'org) +(defcustom org-select-agenda-window t + "Non-nil means, after creating an agenda, move cursor into Agenda window. +When nil, cursor will remain in the current window." + :group 'org-agenda-window-setup + :type 'boolean) -(defcustom org-table-copy-increment t - "Non-nil means, increment when copying current field with \\[org-table-copy-down]." - :group 'org-table-calculation +(defcustom org-fit-agenda-window t + "Non-nil means, change window size of agenda to fit content." + :group 'org-agenda-window-setup :type 'boolean) -(defcustom org-calc-default-modes - '(calc-internal-prec 12 - calc-float-format (float 5) - calc-angle-mode deg - calc-prefer-frac nil - calc-symbolic-mode nil - calc-date-format (YYYY "-" MM "-" DD " " Www (" " HH ":" mm)) - calc-display-working-message t - ) - "List with Calc mode settings for use in calc-eval for table formulas. -The list must contain alternating symbols (Calc modes variables and values). -Don't remove any of the default settings, just change the values. Org-mode -relies on the variables to be present in the list." - :group 'org-table-calculation - :type 'plist) +(defgroup org-agenda-display nil + "Options concerning what to display initially in Agenda." + :tag "Org Agenda Display" + :group 'org-agenda) -(defcustom org-table-formula-evaluate-inline t - "Non-nil means, TAB and RET evaluate a formula in current table field. -If the current field starts with an equal sign, it is assumed to be a formula -which should be evaluated as described in the manual and in the documentation -string of the command `org-table-eval-formula'. This feature requires the -Emacs calc package. -When this variable is nil, formula calculation is only available through -the command \\[org-table-eval-formula]." - :group 'org-table-calculation +(defcustom org-agenda-show-all-dates t + "Non-nil means, `org-agenda' shows every day in the selected range. +When nil, only the days which actually have entries are shown." + :group 'org-agenda-display :type 'boolean) +(defcustom org-agenda-start-on-weekday 1 + "Non-nil means, start the overview always on the specified weekday. +0 Denotes Sunday, 1 denotes Monday etc. +When nil, always start on the current day." + :group 'org-agenda-display + :type '(choice (const :tag "Today" nil) + (number :tag "Weekday No."))) -(defcustom org-table-formula-use-constants t - "Non-nil means, interpret constants in formulas in tables. -A constant looks like `$c' or `$Grav' and will be replaced before evaluation -by the value given in `org-table-formula-constants', or by a value obtained -from the `constants.el' package." - :group 'org-table-calculation +(defcustom org-agenda-ndays 7 + "Number of days to include in overview display. +Should be 1 or 7." + :group 'org-agenda-display + :type 'number) + +(defcustom org-agenda-use-time-grid t + "Non-nil means, show a time grid in the agenda schedule. +A time grid is a set of lines for specific times (like every two hours between +8:00 and 20:00). The items scheduled for a day at specific times are +sorted in between these lines. +For details about when the grid will be shown, and what it will look like, see +the variable `org-agenda-time-grid'." + :group 'org-agenda-display :type 'boolean) -(defcustom org-table-formula-constants nil - "Alist with constant names and values, for use in table formulas. -The car of each element is a name of a constant, without the `$' before it. -The cdr is the value as a string. For example, if you'd like to use the -speed of light in a formula, you would configure +(defcustom org-agenda-time-grid + '((daily today require-timed) + "----------------" + (800 1000 1200 1400 1600 1800 2000)) - (setq org-table-formula-constants '((\"c\" . \"299792458.\"))) + "The settings for time grid for agenda display. +This is a list of three items. The first item is again a list. It contains +symbols specifying conditions when the grid should be displayed: -and then use it in an equation like `$1*$c'." - :group 'org-table-calculation + daily if the agenda shows a single day + weekly if the agenda shows an entire week + today show grid on current date, independent of daily/weekly display + require-timed show grid only if at least on item has a time specification + +The second item is a string which will be places behing the grid time. + +The third item is a list of integers, indicating the times that should have +a grid line." + :group 'org-agenda-display + :type + '(list + (set :greedy t :tag "Grid Display Options" + (const :tag "Show grid in single day agenda display" daily) + (const :tag "Show grid in weekly agenda display" weekly) + (const :tag "Always show grid for today" today) + (const :tag "Show grid only if any timed entries are present" + require-timed) + (const :tag "Skip grid times already present in an entry" + remove-match)) + (string :tag "Grid String") + (repeat :tag "Grid Times" (integer :tag "Time")))) + +(defcustom org-agenda-sorting-strategy '(time-up category-keep priority-down) + "Sorting structure for the agenda items of a single day. +This is a list of symbols which will be used in sequence to determine +if an entry should be listed before another entry. The following +symbols are recognized: + +time-up Put entries with time-of-day indications first, early first +time-down Put entries with time-of-day indications first, late first +category-keep Keep the default order of categories, corresponding to the + sequence in `org-agenda-files'. +category-up Sort alphabetically by category, A-Z. +category-down Sort alphabetically by category, Z-A. +priority-up Sort numerically by priority, high priority last. +priority-down Sort numerically by priority, high priority first. + +The different possibilities will be tried in sequence, and testing stops +if one comparison returns a \"not-equal\". For example, the default + '(time-up category-keep priority-down) +means: Pull out all entries having a specified time of day and sort them, +in order to make a time schedule for the current day the first thing in the +agenda listing for the day. Of the entries without a time indication, keep +the grouped in categories, don't sort the categories, but keep them in +the sequence given in `org-agenda-files'. Within each category sort by +priority. + +Leaving out `category-keep' would mean that items will be sorted across +categories by priority." + :group 'org-agenda-display :type '(repeat - (cons (string :tag "name") - (string :tag "value")))) + (choice + (const time-up) + (const time-down) + (const category-keep) + (const category-up) + (const category-down) + (const priority-up) + (const priority-down)))) -(defcustom org-table-formula-numbers-only nil - "Non-nil means, calculate only with numbers in table formulas. -Then all input fields will be converted to a number, and the result -must also be a number. When nil, calc's full potential is available -in table calculations, including symbolics etc." - :group 'org-table-calculation +(defcustom org-sort-agenda-notime-is-late t + "Non-nil means, items without time are considered late. +This is only relevant for sorting. When t, items which have no explicit +time like 15:30 will be considered as 24:01, i.e. later than any items which +do have a time. When nil, the default time is before 0:00. You can use this +option to decide if the schedule for today should come before or after timeless +agenda entries." + :group 'org-agenda-display :type 'boolean) -(defcustom org-table-allow-automatic-line-recalculation t - "Non-nil means, lines marked with |#| or |*| will be recomputed automatically. -Automatically means, when TAB or RET or C-c C-c are pressed in the line." - :group 'org-table-calculation - :type 'boolean) + +(defgroup org-agenda-prefix nil + "Options concerning the entry prefix in the Org-mode agenda display." + :tag "Org Agenda Prefix" + :group 'org-agenda) + +(defcustom org-agenda-prefix-format " %-12:c%?-12t% s" + "Format specification for the prefix of items in the agenda buffer. +This format works similar to a printf format, with the following meaning: + + %c the category of the item, \"Diary\" for entries from the diary, or + as given by the CATEGORY keyword or derived from the file name. + %T the first tag of the item. + %t the time-of-day specification if one applies to the entry, in the + format HH:MM + %s Scheduling/Deadline information, a short string + +All specifiers work basically like the standard `%s' of printf, but may +contain two additional characters: A question mark just after the `%' and +a whitespace/punctuation character just before the final letter. + +If the first character after `%' is a question mark, the entire field +will only be included if the corresponding value applies to the +current entry. This is useful for fields which should have fixed +width when present, but zero width when absent. For example, +\"%?-12t\" will result in a 12 character time field if a time of the +day is specified, but will completely disappear in entries which do +not contain a time. + +If there is punctuation or whitespace character just before the final +format letter, this character will be appended to the field value if +the value is not empty. For example, the format \"%-12:c\" leads to +\"Diary: \" if the category is \"Diary\". If the category were be +empty, no additional colon would be interted. + +The default value of this option is \" %-12:c%?-12t% s\", meaning: +- Indent the line with two space characters +- Give the category in a 12 chars wide field, padded with whitespace on + the right (because of `-'). Append a colon if there is a category + (because of `:'). +- If there is a time-of-day, put it into a 12 chars wide field. If no + time, don't put in an empty field, just skip it (because of '?'). +- Finally, put the scheduling information and append a whitespace. + +As another example, if you don't want the time-of-day of entries in +the prefix, you could use: + + (setq org-agenda-prefix-format \" %-11:c% s\") + +See also the variables `org-agenda-remove-times-when-in-prefix' and +`org-agenda-remove-tags-when-in-prefix'." + :type 'string + :group 'org-agenda-prefix) + +(defcustom org-timeline-prefix-format " % s" + "Like `org-agenda-prefix-format', but for the timeline of a single file." + :type 'string + :group 'org-agenda-prefix) + +(defvar org-prefix-format-compiled nil + "The compiled version of the most recently used prefix format. +Depending on which command was used last, this may be the compiled version +of `org-agenda-prefix-format' or `org-timeline-prefix-format'.") + +(defcustom org-agenda-remove-times-when-in-prefix t + "Non-nil means, remove duplicate time specifications in agenda items. +When the format `org-agenda-prefix-format' contains a `%t' specifier, a +time-of-day specification in a headline or diary entry is extracted and +placed into the prefix. If this option is non-nil, the original specification +\(a timestamp or -range, or just a plain time(range) specification like +11:30-4pm) will be removed for agenda display. This makes the agenda less +cluttered. +The option can be t or nil. It may also be the symbol `beg', indicating +that the time should only be removed what it is located at the beginning of +the headline/diary entry." + :group 'org-agenda-prefix + :type '(choice + (const :tag "Always" t) + (const :tag "Never" nil) + (const :tag "When at beginning of entry" beg))) + +(defcustom org-agenda-remove-tags-when-in-prefix nil + "Non-nil means, the tags from copy of headline in agenda. +When this is the symbol `prefix', only remove tags when +`org-agenda-prefix-format' contains a `%T' specifier." + :group 'org-agenda-prefix + :type '(choice + (const :tag "Always" t) + (const :tag "Never" nil) + (const :tag "When prefix format contains %T" prefix))) (defgroup org-export nil "Options for exporting org-listings." :tag "Org Export" :group 'org) +(defgroup org-export-general nil + "General options for exporting Org-mode files." + :tag "Org Export General" + :group 'org-export) + (defcustom org-export-language-setup '(("en" "Author" "Date" "Table of Contents") ("da" "Ophavsmand" "Dato" "Indhold") @@ -1512,7 +1571,7 @@ Automatically means, when TAB or RET or C-c C-c are pressed in the line." "Terms used in export text, translated to different languages. Use the variable `org-export-default-language' to set the language, or use the +OPTION lines for a per-file setting." - :group 'org-export + :group 'org-export-general :type '(repeat (list (string :tag "HTML language tag") @@ -1523,53 +1582,7 @@ or use the +OPTION lines for a per-file setting." (defcustom org-export-default-language "en" "The default language of HTML export, as a string. This should have an association in `org-export-language-setup'." - :group 'org-export - :type 'string) - -(defcustom org-export-html-style -"<style type=\"text/css\"> - html { - font-family: Times, serif; - font-size: 12pt; - } - .title { text-align: center; } - .todo, .deadline { color: red; } - .done { color: green; } - .target { background-color: lavender; } - pre { - border: 1pt solid #AEBDCC; - background-color: #F3F5F7; - padding: 5pt; - font-family: courier, monospace; - } - table { border-collapse: collapse; } - td, th { - vertical-align: top; - border: 1pt solid #ADB9CC; - } -</style>" - "The default style specification for exported HTML files. -Since there are different ways of setting style information, this variable -needs to contain the full HTML structure to provide a style, including the -surrounding HTML tags. The style specifications should include definitions -for new classes todo, done, title, and deadline. For example, legal values -would be: - - <style type=\"text/css\"> - p { font-weight: normal; color: gray; } - h1 { color: black; } - .title { text-align: center; } - .todo, .deadline { color: red; } - .done { color: green; } - </style> - -or, if you want to keep the style in a file, - - <link rel=\"stylesheet\" type=\"text/css\" href=\"mystyles.css\"> - -As the value of this option simply gets inserted into the HTML <head> header, -you can \"misuse\" it to add arbitrary text to the header." - :group 'org-export + :group 'org-export-general :type 'string) (defcustom org-export-headline-levels 3 @@ -1579,14 +1592,14 @@ Note that a numeric prefix argument to an exporter function overrides this setting. This option can also be set with the +OPTIONS line, e.g. \"H:2\"." - :group 'org-export + :group 'org-export-general :type 'number) (defcustom org-export-with-section-numbers t "Non-nil means, add section numbers to headlines when exporting. This option can also be set with the +OPTIONS line, e.g. \"num:t\"." - :group 'org-export + :group 'org-export-general :type 'boolean) (defcustom org-export-with-toc t @@ -1599,7 +1612,7 @@ ASCII export, and with red color in HTML output. In HTML output, the TOC will be clickable. This option can also be set with the +OPTIONS line, e.g. \"toc:nil\"." - :group 'org-export + :group 'org-export-general :type 'boolean) (defcustom org-export-plain-list-max-depth 20 @@ -1621,7 +1634,7 @@ formatted correctly in HTML: - Pineapple * Bread * Dairy products" - :group 'org-export + :group 'org-export-general :type 'integer) (defcustom org-export-preserve-breaks nil @@ -1630,24 +1643,59 @@ Normally, in HTML output paragraphs will be reformatted. In ASCII export, line breaks will always be preserved, regardless of this variable. This option can also be set with the +OPTIONS line, e.g. \"\\n:t\"." - :group 'org-export + :group 'org-export-general :type 'boolean) -(defcustom org-export-html-inline-images t - "Non-nil means, inline images into exported HTML pages. -The link will still be to the original location of the image file. -So if you are moving the page, lets say to your public HTML site, -you will have to move the image and maybe change the link." - :group 'org-export +(defcustom org-export-with-emphasize t + "Non-nil means, interpret *word*, /word/, and _word_ as emphasized text. +If the export target supports emphasizing text, the word will be +typeset in bold, italic, or underlined, respectively. Works only for +single words, but you can say: I *really* *mean* *this*. +Not all export backends support this. + +This option can also be set with the +OPTIONS line, e.g. \"*:nil\"." + :group 'org-export-general :type 'boolean) -(defcustom org-export-html-expand t - "Non-nil means, for HTML export, treat @<...> as HTML tag. -When nil, these tags will be exported as plain text and therefore -not be interpreted by a browser. +;; FIXME: Is this in the right place???? +(defcustom org-match-sexp-depth 3 + "Number of stacked braces for sub/superscript matching. +This has to be set before loading org.el to be effective." + :group 'org-export-general + :type 'integer) -This option can also be set with the +OPTIONS line, e.g. \"@:nil\"." - :group 'org-export +(defcustom org-export-with-sub-superscripts t + "Non-nil means, interpret \"_\" and \"^\" for export. +When this option is turned on, you can use TeX-like syntax for sub- and +superscripts. Several characters after \"_\" or \"^\" will be +considered as a single item - so grouping with {} is normally not +needed. For example, the following things will be parsed as single +sub- or superscripts. + + 10^24 or 10^tau several digits will be considered 1 item. + 10^-12 or 10^-tau a leading sign with digits or a word + x^2-y^3 will be read as x^2 - y^3, because items are + terminated by almost any nonword/nondigit char. + x_{i^2} or x^(2-i) braces or parenthesis do grouping. + +Still, ambiguity is possible - so when in doubt use {} to enclose the +sub/superscript. +Not all export backends support this. + +This option can also be set with the +OPTIONS line, e.g. \"^:nil\"." + :group 'org-export-general + :type 'boolean) + +(defcustom org-export-with-TeX-macros t + "Non-nil means, interpret simple TeX-like macros when exporting. +For example, HTML export converts \\alpha to α and \\AA to Å. +No only real TeX macros will work here, but the standard HTML entities +for math can be used as macro names as well. For a list of supported +names in HTML export, see the constant `org-html-entities'. +Not all export backends support this. + +This option can also be set with the +OPTIONS line, e.g. \"TeX:nil\"." + :group 'org-export-general :type 'boolean) (defcustom org-export-with-fixed-width t @@ -1657,11 +1705,11 @@ example: : ;; Some Lisp examples : (while (defc cnt) : (ding)) -will be looking just like this in also HTML. In ASCII export, this option -has no effect. +will be looking just like this in also HTML. +Not all export backends support this. This option can also be set with the +OPTIONS line, e.g. \"::nil\"." - :group 'org-export + :group 'org-export-general :type 'boolean) (defcustom org-export-with-tables t @@ -1672,10 +1720,19 @@ For example: |-------------+----------+-----------| | Arthur Dent | England | 29.2.2100 | -In ASCII export, this option has no effect. +Not all export backends support this. This option can also be set with the +OPTIONS line, e.g. \"|:nil\"." - :group 'org-export + :group 'org-export-general + :type 'boolean) + +(defcustom org-export-highlight-first-table-line t + "Non-nil means, highlight the first table line. +In HTML export, this means use <th> instead of <td>. +In tables created with table.el, this applies to the first table line. +In Org-mode tables, all lines before the first horizontal separator +line will be formatted with <th> tags." + :group 'org-export-general :type 'boolean) (defcustom org-export-table-remove-special-lines t @@ -1684,7 +1741,7 @@ This removes the special marking character column from tables that are set up for spreadsheet calculations. It also removes the entire lines marked with `!', `_', or `^'. The lines with `$' are kept, because the values of constants may be useful to have." - :group 'org-export + :group 'org-export-general :type 'boolean) (defcustom org-export-prefer-native-exporter-for-tables nil @@ -1695,112 +1752,151 @@ the table does not use row- or column-spanning). This has the advantage, that the automatic HTML conversions for math symbols and sub/superscripts can be applied. Org-mode's HTML generator is also much faster." - :group 'org-export + :group 'org-export-general :type 'boolean) -(defcustom org-export-html-table-tag - "<table border=1 cellspacing=0 cellpadding=6>" - "The HTML tag used to start a table. -This must be a <table> tag, but you may change the options like -borders and spacing." - :group 'org-export - :type 'string) - -(defcustom org-export-with-emphasize t - "Non-nil means, interpret *word*, /word/, and _word_ as emphasized text. -If the export target supports emphasizing text, the word will be -typeset in bold, italic, or underlined, respectively. Works only for -single words, but you can say: I *really* *mean* *this*. -In ASCII export, this option has no effect. +(defgroup org-export-ascii nil + "Options specific for ASCII export of Org-mode files." + :tag "Org Export ASCII" + :group 'org-export) -This option can also be set with the +OPTIONS line, e.g. \"*:nil\"." - :group 'org-export +(defcustom org-export-ascii-show-new-buffer t + "Non-nil means, popup buffer containing the exported ASCII text. +Otherwise the buffer will just be saved to a file and stay hidden." + :group 'org-export-ascii :type 'boolean) -(defcustom org-match-sexp-depth 3 - "Number of stacked braces for sub/superscript matching. -This has to be set before loading org.el to be effective." - :group 'org-export - :type 'integer) +(defgroup org-export-xml nil + "Options specific for XML export of Org-mode files." + :tag "Org Export XML" + :group 'org-export) -;; FIXME: Should () parens be removed as well in sub/superscripts? -(defcustom org-export-with-sub-superscripts t - "Non-nil means, interpret \"_\" and \"^\" for export. -When this option is turned on, you can use TeX-like syntax for sub- and -superscripts. Several characters after \"_\" or \"^\" will be -considered as a single item - so grouping with {} is normally not -needed. For example, the following things will be parsed as single -sub- or superscripts. +(defcustom org-export-xml-type 'xoxo + "The kind of XML to be produced by the XML exporter. +Allowed values are: +xoxo The XOXO exporter." + :group 'org-export-xml + :type '(choice + (const :tag "XOXO" xoxo))) - 10^24 or 10^tau several digits will be considered 1 item. - 10^-12 or 10^-tau a leading sign with digits or a word - x^2-y^3 will be read as x^2 - y^3, because items are - terminated by almost any nonword/nondigit char. - x_{i^2} or x^(2-i) braces or parenthesis do grouping. +(defgroup org-export-html nil + "Options specific for HTML export of Org-mode files." + :tag "Org Export HTML" + :group 'org-export) -Still, ambiguity is possible - so when in doubt use {} to enclose the -sub/superscript. -In ASCII export, this option has no effect. +(defcustom org-export-html-style +"<style type=\"text/css\"> + html { + font-family: Times, serif; + font-size: 12pt; + } + .title { text-align: center; } + .todo, .deadline { color: red; } + .done { color: green; } + .target { background-color: lavender; } + pre { + border: 1pt solid #AEBDCC; + background-color: #F3F5F7; + padding: 5pt; + font-family: courier, monospace; + } + table { border-collapse: collapse; } + td, th { + vertical-align: top; + border: 1pt solid #ADB9CC; + } +</style>" + "The default style specification for exported HTML files. +Since there are different ways of setting style information, this variable +needs to contain the full HTML structure to provide a style, including the +surrounding HTML tags. The style specifications should include definitions +for new classes todo, done, title, and deadline. For example, legal values +would be: -This option can also be set with the +OPTIONS line, e.g. \"^:nil\"." - :group 'org-export + <style type=\"text/css\"> + p { font-weight: normal; color: gray; } + h1 { color: black; } + .title { text-align: center; } + .todo, .deadline { color: red; } + .done { color: green; } + </style> + +or, if you want to keep the style in a file, + + <link rel=\"stylesheet\" type=\"text/css\" href=\"mystyles.css\"> + +As the value of this option simply gets inserted into the HTML <head> header, +you can \"misuse\" it to add arbitrary text to the header." + :group 'org-export-html + :type 'string) + +(defcustom org-export-html-inline-images t + "Non-nil means, inline images into exported HTML pages. +The link will still be to the original location of the image file. +So if you are moving the page, lets say to your public HTML site, +you will have to move the image and maybe change the link." + :group 'org-export-html :type 'boolean) -(defcustom org-export-with-TeX-macros t - "Non-nil means, interpret simple TeX-like macros when exporting. -For example, HTML export converts \\alpha to α and \\AA to Å. -No only real TeX macros will work here, but the standard HTML entities -for math can be used as macro names as well. For a list of supported -names in HTML export, see the constant `org-html-entities'. -In ASCII export, this option has no effect. +(defcustom org-export-html-expand t + "Non-nil means, for HTML export, treat @<...> as HTML tag. +When nil, these tags will be exported as plain text and therefore +not be interpreted by a browser. -This option can also be set with the +OPTIONS line, e.g. \"TeX:nil\"." - :group 'org-export +This option can also be set with the +OPTIONS line, e.g. \"@:nil\"." + :group 'org-export-html :type 'boolean) +(defcustom org-export-html-table-tag + "<table border=1 cellspacing=0 cellpadding=6>" + "The HTML tag used to start a table. +This must be a <table> tag, but you may change the options like +borders and spacing." + :group 'org-export-html + :type 'string) + (defcustom org-export-html-with-timestamp nil "If non-nil, write `org-export-html-html-helper-timestamp' into the exported HTML text. Otherwise, the buffer will just be saved to a file." - :group 'org-export + :group 'org-export-html :type 'boolean) (defcustom org-export-html-html-helper-timestamp "<br><br><hr><p><!-- hhmts start --> <!-- hhmts end -->\n" "The HTML tag used as timestamp delimiter for HTML-helper-mode." - :group 'org-export + :group 'org-export-html :type 'string) -(defcustom org-export-ascii-show-new-buffer t - "Non-nil means, popup buffer containing the exported ASCII text. -Otherwise the buffer will just be saved to a file and stay hidden." - :group 'org-export - :type 'boolean) - (defcustom org-export-html-show-new-buffer nil "Non-nil means, popup buffer containing the exported html text. Otherwise, the buffer will just be saved to a file and stay hidden." - :group 'org-export + :group 'org-export-html :type 'boolean) +(defgroup org-export-icalendar nil + "Options specific for iCalendar export of Org-mode files." + :tag "Org Export iCalendar" + :group 'org-export) + (defcustom org-combined-agenda-icalendar-file "~/org.ics" "The file name for the iCalendar file covering all agenda files. This file is created with the command \\[org-export-icalendar-all-agenda-files]." - :group 'org-export + :group 'org-export-icalendar :type 'file) (defcustom org-icalendar-include-todo nil "Non-nil means, export to iCalendar files should also cover TODO items." - :group 'org-export + :group 'org-export-icalendar :type 'boolean) (defcustom org-icalendar-combined-name "OrgMode" "Calendar name for the combined iCalendar representing all agenda files." - :group 'org-export + :group 'org-export-icalendar :type 'string) (defgroup org-font-lock nil - "Faces and settings for highlighting in Org-mode." + "Font-lock settings for highlighting in Org-mode." :tag "Org Font Lock" :group 'org) @@ -1837,6 +1933,11 @@ Changing this variable requires a restart of Emacs to take effect." :group 'org-font-lock :type 'boolean) +(defgroup org-faces nil + "Faces in Org-mode." + :tag "Org Faces" + :group 'org-font-lock) + (defface org-hide '( (((type tty) (class color)) (:foreground "white")) @@ -1844,7 +1945,7 @@ Changing this variable requires a restart of Emacs to take effect." (((class color) (background dark)) (:foreground "black")) (t (:inverse-video nil))) "Face used for level 1 headlines." - :group 'org-font-lock) + :group 'org-faces) (defface org-level-1 ;; font-lock-function-name-face '((((type tty) (class color)) (:foreground "blue" :weight bold)) @@ -1852,7 +1953,7 @@ Changing this variable requires a restart of Emacs to take effect." (((class color) (background dark)) (:foreground "LightSkyBlue")) (t (:inverse-video t :bold t))) "Face used for level 1 headlines." - :group 'org-font-lock) + :group 'org-faces) (defface org-level-2 ;; font-lock-variable-name-face '((((type tty) (class color)) (:foreground "yellow" :weight light)) @@ -1860,7 +1961,7 @@ Changing this variable requires a restart of Emacs to take effect." (((class color) (background dark)) (:foreground "LightGoldenrod")) (t (:bold t :italic t))) "Face used for level 2 headlines." - :group 'org-font-lock) + :group 'org-faces) (defface org-level-3 ;; font-lock-keyword-face '((((type tty) (class color)) (:foreground "cyan" :weight bold)) @@ -1868,7 +1969,7 @@ Changing this variable requires a restart of Emacs to take effect." (((class color) (background dark)) (:foreground "Cyan")) (t (:bold t))) "Face used for level 3 headlines." - :group 'org-font-lock) + :group 'org-faces) (defface org-level-4 ;; font-lock-comment-face '((((type tty pc) (class color) (background light)) (:foreground "red")) @@ -1877,7 +1978,7 @@ Changing this variable requires a restart of Emacs to take effect." (((class color) (background dark)) (:foreground "chocolate1")) (t (:bold t :italic t))) "Face used for level 4 headlines." - :group 'org-font-lock) + :group 'org-faces) (defface org-level-5 ;; font-lock-type-face '((((type tty) (class color)) (:foreground "green")) @@ -1885,7 +1986,7 @@ Changing this variable requires a restart of Emacs to take effect." (((class color) (background dark)) (:foreground "PaleGreen")) (t (:bold t :underline t))) "Face used for level 5 headlines." - :group 'org-font-lock) + :group 'org-faces) (defface org-level-6 ;; font-lock-constant-face '((((type tty) (class color)) (:foreground "magenta")) @@ -1893,7 +1994,7 @@ Changing this variable requires a restart of Emacs to take effect." (((class color) (background dark)) (:foreground "Aquamarine")) (t (:bold t :underline t))) "Face used for level 6 headlines." - :group 'org-font-lock) + :group 'org-faces) (defface org-level-7 ;; font-lock-builtin-face '((((type tty) (class color)) (:foreground "blue" :weight light)) @@ -1901,7 +2002,7 @@ Changing this variable requires a restart of Emacs to take effect." (((class color) (background dark)) (:foreground "LightSteelBlue")) (t (:bold t))) "Face used for level 7 headlines." - :group 'org-font-lock) + :group 'org-faces) (defface org-level-8 ;; font-lock-string-face '((((type tty) (class color)) (:foreground "green")) @@ -1909,7 +2010,7 @@ Changing this variable requires a restart of Emacs to take effect." (((class color) (background dark)) (:foreground "LightSalmon")) (t (:italic t))) "Face used for level 8 headlines." - :group 'org-font-lock) + :group 'org-faces) (defface org-special-keyword ;; font-lock-string-face '((((type tty) (class color)) (:foreground "green")) @@ -1917,7 +2018,7 @@ Changing this variable requires a restart of Emacs to take effect." (((class color) (background dark)) (:foreground "LightSalmon")) (t (:italic t))) "Face used for special keywords." - :group 'org-font-lock) + :group 'org-faces) (defface org-warning ;; font-lock-warning-face '((((type tty) (class color)) (:foreground "red")) @@ -1926,7 +2027,7 @@ Changing this variable requires a restart of Emacs to take effect." ; (((class color) (background dark)) (:foreground "Pink" :bold t)) (t (:inverse-video t :bold t))) "Face for deadlines and TODO keywords." - :group 'org-font-lock) + :group 'org-faces) (defface org-headline-done ;; font-lock-string-face '((((type tty) (class color)) (:foreground "green")) @@ -1935,7 +2036,7 @@ Changing this variable requires a restart of Emacs to take effect." (t (:italic t))) "Face used to indicate that a headline is DONE. See also the variable `org-fontify-done-headline'." - :group 'org-font-lock) + :group 'org-faces) ;; Inheritance does not work for xemacs. So we just copy... @@ -1945,7 +2046,7 @@ Changing this variable requires a restart of Emacs to take effect." (((class color) (background dark)) (:foreground "LightSkyBlue")) (t (:inverse-video t :bold t))) "Face for upcoming deadlines." - :group 'org-font-lock) + :group 'org-faces) (defface org-scheduled-today '((((type tty) (class color)) (:foreground "green")) @@ -1953,7 +2054,7 @@ Changing this variable requires a restart of Emacs to take effect." (((class color) (background dark)) (:foreground "PaleGreen")) (t (:bold t :underline t))) "Face for items scheduled for a certain day." - :group 'org-font-lock) + :group 'org-faces) (defface org-scheduled-previously '((((type tty pc) (class color) (background light)) (:foreground "red")) @@ -1962,7 +2063,7 @@ Changing this variable requires a restart of Emacs to take effect." (((class color) (background dark)) (:foreground "chocolate1")) (t (:bold t :italic t))) "Face for items scheduled previously, and not yet done." - :group 'org-font-lock) + :group 'org-faces) (defface org-formula '((((type tty pc) (class color) (background light)) (:foreground "red")) @@ -1971,7 +2072,7 @@ Changing this variable requires a restart of Emacs to take effect." (((class color) (background dark)) (:foreground "chocolate1")) (t (:bold t :italic t))) "Face for formulas." - :group 'org-font-lock) + :group 'org-faces) (defface org-link '((((type tty) (class color)) (:foreground "cyan" :weight bold)) @@ -1979,7 +2080,7 @@ Changing this variable requires a restart of Emacs to take effect." (((class color) (background dark)) (:foreground "Cyan" :underline t)) (t (:bold t))) "Face for links." - :group 'org-font-lock) + :group 'org-faces) (defface org-tag '((((type tty) (class color)) (:weight bold)) @@ -1987,7 +2088,7 @@ Changing this variable requires a restart of Emacs to take effect." (((class color) (background dark)) (:weight bold)) (t (:bold t))) "Face for tags." - :group 'org-font-lock) + :group 'org-faces) (defface org-done ;; font-lock-type-face '((((type tty) (class color)) (:foreground "green")) @@ -1995,7 +2096,7 @@ Changing this variable requires a restart of Emacs to take effect." (((class color) (background dark)) (:foreground "PaleGreen" :bold t)) (t (:bold t :underline t))) "Face used for DONE." - :group 'org-font-lock) + :group 'org-faces) (defface org-table ;; font-lock-function-name-face '((((type tty) (class color)) (:foreground "blue" :weight bold)) @@ -2003,7 +2104,7 @@ Changing this variable requires a restart of Emacs to take effect." (((class color) (background dark)) (:foreground "LightSkyBlue")) (t (:inverse-video t :bold t))) "Face used for tables." - :group 'org-font-lock) + :group 'org-faces) (defface org-time-grid ;; font-lock-variable-name-face '((((type tty) (class color)) (:foreground "yellow" :weight light)) @@ -2011,7 +2112,7 @@ Changing this variable requires a restart of Emacs to take effect." (((class color) (background dark)) (:foreground "LightGoldenrod")) (t (:bold t :italic t))) "Face used for time grids." - :group 'org-font-lock) + :group 'org-faces) (defvar org-level-faces '(org-level-1 org-level-2 org-level-3 org-level-4 @@ -2019,6 +2120,51 @@ Changing this variable requires a restart of Emacs to take effect." )) (defvar org-n-levels (length org-level-faces)) + +;; Variables for pre-computed regular expressions, all buffer local +(defvar org-done-string nil + "The last string in `org-todo-keywords', indicating an item is DONE.") +(make-variable-buffer-local 'org-done-string) +(defvar org-todo-regexp nil + "Matches any of the TODO state keywords.") +(make-variable-buffer-local 'org-todo-regexp) +(defvar org-not-done-regexp nil + "Matches any of the TODO state keywords except the last one.") +(make-variable-buffer-local 'org-not-done-regexp) +(defvar org-todo-line-regexp nil + "Matches a headline and puts TODO state into group 2 if present.") +(make-variable-buffer-local 'org-todo-line-regexp) +(defvar org-nl-done-regexp nil + "Matches newline followed by a headline with the DONE keyword.") +(make-variable-buffer-local 'org-nl-done-regexp) +(defvar org-looking-at-done-regexp nil + "Matches the DONE keyword a point.") +(make-variable-buffer-local 'org-looking-at-done-regexp) +(defvar org-todo-kwd-priority-p nil + "Do TODO items have priorities?") +(make-variable-buffer-local 'org-todo-kwd-priority-p) +(defvar org-todo-kwd-max-priority nil + "Maximum priority of TODO items.") +(make-variable-buffer-local 'org-todo-kwd-max-priority) +(defvar org-ds-keyword-length 12 + "Maximum length of the Deadline and SCHEDULED keywords.") +(make-variable-buffer-local 'org-ds-keyword-length) +(defvar org-deadline-regexp nil + "Matches the DEADLINE keyword.") +(make-variable-buffer-local 'org-deadline-regexp) +(defvar org-deadline-time-regexp nil + "Matches the DEADLINE keyword together with a time stamp.") +(make-variable-buffer-local 'org-deadline-time-regexp) +(defvar org-deadline-line-regexp nil + "Matches the DEADLINE keyword and the rest of the line.") +(make-variable-buffer-local 'org-deadline-line-regexp) +(defvar org-scheduled-regexp nil + "Matches the SCHEDULED keyword.") +(make-variable-buffer-local 'org-scheduled-regexp) +(defvar org-scheduled-time-regexp nil + "Matches the SCHEDULED keyword together with a time stamp.") +(make-variable-buffer-local 'org-scheduled-time-regexp) + (defun org-set-regexps-and-options () "Precompute regular expressions for current buffer." (when (eq major-mode 'org-mode) @@ -2152,7 +2298,7 @@ Changing this variable requires a restart of Emacs to take effect." (defvar remember-data-file) ; from remember.el (defvar annotation) ; from remember.el, dynamically scoped in `remember-mode' (defvar initial) ; from remember.el, dynamically scoped in `remember-mode' - +(defvar orgtbl-mode) ; defined later in this file ;;; Define the mode (defvar org-mode-map (copy-keymap outline-mode-map) @@ -2198,10 +2344,16 @@ The following commands are available: (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-regexp "\\(?:\\*+\\|[ \t]*\\(?:[-+*]\\|[0-9]+[.)]\\) \\)") (setq outline-level 'org-outline-level) - (if org-startup-truncated (setq truncate-lines t)) + (when (and org-ellipsis (stringp org-ellipsis)) + (unless org-display-table + (setq org-display-table (make-display-table))) + (set-display-table-slot org-display-table + 4 (string-to-vector org-ellipsis)) + (setq buffer-display-table org-display-table)) (org-set-regexps-and-options) + (if org-startup-truncated (setq truncate-lines t)) (set (make-local-variable 'font-lock-unfontify-region-function) 'org-unfontify-region) ;; Activate before-change-function @@ -2262,7 +2414,7 @@ The following commands are available: (nthcdr 2 time)))) (current-time))) -;; FIXME: Do we need to copy? +;; FIXME: `propertize' does copy the string first... (defun org-string-props (string &rest properties) "Add PROPERTIES to string." (add-text-properties 0 (length string) properties string) @@ -2285,27 +2437,47 @@ 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-non-link-chars "]\t\n\r|<>\000") +(defconst org-link-types '("https?" "ftp" "mailto" "file" "news" "bbdb" "vm" + "wl" "mhe" "rmail" "gnus" "shell")) +(defconst org-link-re-with-space + (concat + "<?\\(" (mapconcat 'identity org-link-types "\\|") "\\):" + "\\([^" org-non-link-chars " ]" + "[^" org-non-link-chars "]*" + "[^" org-non-link-chars " ]\\)>?")) +(defconst org-link-re-no-space + (concat + "<?\\(" (mapconcat 'identity org-link-types "\\|") "\\):" + "\\([^" org-non-link-chars " ]+\\)>?")) (defconst org-link-regexp - (if org-allow-space-in-links - (concat - "\\(https?\\|ftp\\|mailto\\|file\\|news\\|bbdb\\|vm\\|wl\\|mhe\\|rmail\\|gnus\\|shell\\):\\([^" org-non-link-chars "]+[^ " org-non-link-chars "]\\)") - (concat - "\\(https?\\|ftp\\|mailto\\|file\\|news\\|bbdb\\|vm\\|wl\\|mhe\\|rmail\\|gnus\\|shell\\):\\([^ " org-non-link-chars "]+\\)") - ) - "Regular expression for matching links.") -(defconst org-link-maybe-angles-regexp - (concat "<?\\(" org-link-regexp "\\)>?") - "Matches a link and optionally surrounding angle brackets.") -(defconst org-protected-link-regexp - (concat "\000" org-link-regexp "\000") - "Matches a link and optionally surrounding angle brackets.") + (if org-allow-space-in-plain-links + org-link-re-with-space + org-link-re-no-space) + "Regular expression for matching links in plain text.") +(defconst org-external-link-maybe-brackets + (concat "\\(\\[\\[\\)?\\(" org-link-regexp "\\)\\(\\]\\(\\]\\|\\[\\)\\)?") + "Matches a link and optionally surrounding brackets.") (defconst org-bracket-link-regexp "\\[\\[\\([^]]+\\)\\]\\(\\[\\([^]]+\\)\\]\\)?\\]" "Matches a link in double brackets.") +(defconst org-bracket-link-analytic-regexp + (concat + "\\[\\[" + "\\(\\(" (mapconcat 'identity org-link-types "\\|") "\\):\\)?" + "\\([^]]+\\)" + "\\]" + "\\(\\[" "\\([^]]+\\)" "\\]\\)?" + "\\]")) +; 1: http: +; 2: http +; 3: path +; 4: [desc] +; 5: desc + + (defconst org-ts-lengths (cons (length (format-time-string (car org-time-stamp-formats))) (length (format-time-string (cdr org-time-stamp-formats)))) @@ -2344,8 +2516,8 @@ The following commands are available: (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. + ;; We need to remove the invisible property here. Table narrowing + ;; may have made some of this invisible. (remove-text-properties (match-beginning 0) (match-end 0) '(invisible nil)) (if (match-end 3) @@ -2487,7 +2659,7 @@ between words." '(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 append)) + '(org-activate-tags (1 'org-tag prepend)) '(org-hide-wide-columns (0 nil append)) (list (concat "^\\*+[ \t]*" org-not-done-regexp) '(1 'org-warning t)) @@ -2495,9 +2667,9 @@ between words." (list (concat "\\<" org-deadline-string) '(0 'org-special-keyword t)) (list (concat "\\<" org-scheduled-string) '(0 'org-special-keyword t)) (list (concat "\\<" org-closed-string) '(0 'org-special-keyword t)) - (if em '("\\(\\W\\|^\\)\\(\\*\\w+\\*\\)\\(\\W\\|$\\)" 2 'bold append)) - (if em '("\\(\\W\\|^\\)\\(/\\w+/\\)\\(\\W\\|$\\)" 2 'italic append)) - (if em '("\\(\\W\\|^\\)\\(_\\w+_\\)\\(\\W\\|$\\)" 2 'underline append)) + (if em '("\\(\\W\\|^\\)\\(\\*\\w+\\*\\)\\(\\W\\|$\\)" 2 'bold prepend)) + (if em '("\\(\\W\\|^\\)\\(/\\w+/\\)\\(\\W\\|$\\)" 2 'italic prepend)) + (if em '("\\(\\W\\|^\\)\\(_\\w+_\\)\\(\\W\\|$\\)" 2 'underline prepend)) (list (concat "^\\*+[ \t]*\\<\\(" org-comment-string "\\|" org-quote-string "\\)\\>") '(1 'org-special-keyword t)) @@ -2545,9 +2717,6 @@ between words." (remove-text-properties beg end '(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 (defvar org-cycle-global-status nil) @@ -2597,8 +2766,9 @@ between words." ;; Enter the table or move to the next field in the table (or (org-table-recognize-table.el) (progn - (org-table-justify-field-maybe) - (org-table-next-field)))) + (if arg (org-table-edit-field t) + (org-table-justify-field-maybe) + (org-table-next-field))))) ((eq arg t) ;; Global cycling @@ -2709,13 +2879,14 @@ between words." (defun org-optimize-window-after-visibility-change (state) "Adjust the window after a change in outline visibility. This function is the default value of the hook `org-cycle-hook'." - (cond - ((eq state 'overview) (org-first-headline-recenter 1)) - ((eq state 'content) nil) - ((eq state 'all) nil) - ((eq state 'folded) nil) - ((eq state 'children) (or (org-subtree-end-visible-p) (recenter 1))) - ((eq state 'subtree) (or (org-subtree-end-visible-p) (recenter 1))))) + (when (get-buffer-window (current-buffer)) + (cond + ((eq state 'overview) (org-first-headline-recenter 1)) + ((eq state 'content) nil) + ((eq state 'all) nil) + ((eq state 'folded) nil) + ((eq state 'children) (or (org-subtree-end-visible-p) (recenter 1))) + ((eq state 'subtree) (or (org-subtree-end-visible-p) (recenter 1)))))) (defun org-subtree-end-visible-p () "Is the end of the current subtree visible?" @@ -2879,10 +3050,8 @@ or nil." (funcall outline-level))))) (unless (bolp) (newline)) (insert head) - (unless (eolp) - (save-excursion (newline-and-indent))) - (unless (equal (char-before) ?\ ) - (insert " ")) + (if (looking-at "[ \t]*") + (replace-match " ")) (run-hooks 'org-insert-heading-hook)))) (defun org-insert-item () @@ -4026,7 +4195,6 @@ An inactive time stamp is enclosed in square brackets instead of angle brackets. It is inactive in the sense that it does not trigger agenda entries, does not link to the calendar and cannot be changed with the S-cursor keys. So these are more for recording a certain time/date." - ;; FIXME: Would it be better not to ask for a date/time here? (interactive "P") (let ((fmt (if arg (cdr org-time-stamp-formats) (car org-time-stamp-formats))) @@ -4041,8 +4209,6 @@ So these are more for recording a certain time/date." (org-overlay-put org-date-ovl 'face 'org-warning) (org-detatch-overlay org-date-ovl) -;;; FIXME: Make the function take "Fri" as "next friday" -;;; because these are mostly being used to record the current time. (defun org-read-date (&optional with-time to-time) "Read a date and make things smooth for the user. The prompt will suggest to enter an ISO date, but you can also enter anything @@ -4055,6 +4221,7 @@ hour and minute. For example, 12:45 --> today 12:45 22 sept 0:34 --> currentyear-09-22 0:34 12 --> currentyear-currentmonth-12 + Fri --> nearest Friday (today or later) etc. The function understands only English month and weekday abbreviations, but this can be configured with the variables `parse-time-months' and @@ -4086,7 +4253,7 @@ used to insert the time stamp into the buffer to include the time." (- (point) 20) t)) (apply 'encode-time - (mapcar (lambda(x) (or x 0)) ;; FIXME: Problem with timezone? + (mapcar (lambda(x) (or x 0)) (parse-time-string (match-string 1)))) ct)) (calendar-move-hook nil) @@ -4095,11 +4262,9 @@ used to insert the time stamp into the buffer to include the time." (if with-time "%Y-%m-%d %H:%M" "%Y-%m-%d") default-time)) (prompt (format "YYYY-MM-DD [%s]: " timestr)) ans ans1 ans2 - second minute hour day month year tl) + second minute hour day month year tl wday wday1) (if org-popup-calendar-for-date-prompt - ;; Also show a calendar for date selection - ;; Copied (with modifications) from planner.el by John Wiegley (save-excursion (save-window-excursion (calendar) @@ -4167,7 +4332,14 @@ used to insert the time stamp into the buffer to include the time." day (or (nth 3 tl) (string-to-number (format-time-string "%d" ct))) hour (or (nth 2 tl) (string-to-number (format-time-string "%H" ct))) minute (or (nth 1 tl) (string-to-number (format-time-string "%M" ct))) - second (or (nth 0 tl) 0)) + second (or (nth 0 tl) 0) + wday (nth 6 tl)) + (when (and wday (not (nth 3 tl))) + ;; Weekday was given, but no day, so pick that day in the week + ;; on or after the derived date. + (setq wday1 (nth 6 (decode-time (encode-time 0 0 0 day month year)))) + (unless (equal wday wday1) + (setq day (+ day (% (- wday wday1 -7) 7))))) (if (and (boundp 'org-time-was-given) (nth 2 tl)) (setq org-time-was-given t)) @@ -4271,8 +4443,6 @@ days in order to avoid rounding problems." (fd1 "%dd") (fh "%02d:%02d") y d h m align) - ;; FIXME: Should I re-introduce years, make year refer to same date? - ;; This would be the only useful way to have years, actually. (if havetime (setq ; y (floor (/ diff ys)) diff (mod diff ys) y 0 @@ -4808,7 +4978,7 @@ the buffer and restores the previous window configuration." (let ((f org-agenda-files) b) (while (setq b (find-buffer-visiting f)) (kill-buffer b)) (with-temp-file f - (insert (mapconcat 'identity list) "\n") "\n")) + (insert (mapconcat 'identity list "\n") "\n"))) (let ((org-mode-hook nil) (default-major-mode 'fundamental-mode)) (setq org-agenda-files list) (customize-save-variable 'org-agenda-files org-agenda-files)))) @@ -4972,7 +5142,7 @@ NDAYS defaults to `org-agenda-ndays'." (and (null ndays) (equal 1 org-agenda-ndays))) nil org-agenda-start-on-weekday)) (org-agenda-keep-modes keep-modes) - (thefiles (copy-sequence (org-agenda-files))) ;; FIXME: Why copy??? + (thefiles (org-agenda-files)) (files thefiles) (win (selected-window)) (today (time-to-days (current-time))) @@ -5511,9 +5681,6 @@ Optional argument FILE means, use this file instead of the current." (defun org-file-menu-entry (file) (vector file (list 'find-file file) t)) -;; FIXME: Maybe we removed a buffer visited through the menu from -;; org-agenda-new-buffers, so that the buffer will not be removed -;; when exiting the agenda???? (defun org-get-all-dates (beg end &optional no-ranges force-today inactive) "Return a list of all relevant day numbers from BEG to END buffer positions. @@ -6175,7 +6342,7 @@ only the correctly processes TXT should be returned - this is used by (unless (and remove (member time have)) (setq time (int-to-string time)) (push (org-format-agenda-item - nil string "" nil ;; FIXME: put a category for the grid? + nil string "" nil (concat (substring time 0 -2) ":" (substring time -2))) new) (put-text-property @@ -6276,7 +6443,7 @@ HH:MM." (priority-down (if priority-up (- priority-up) nil)) (category-up (org-cmp-category a b)) (category-down (if category-up (- category-up) nil)) - (category-keep (if category-up +1 nil))) ; FIXME +1 or -1? + (category-keep (if category-up +1 nil))) (cdr (assoc (eval (cons 'or org-agenda-sorting-strategy)) '((-1 . t) (1 . nil) (nil . nil)))))) @@ -6935,7 +7102,6 @@ With prefix ARG, realign all tags in headings in the current buffer." (setq hd (match-string 1)) (delete-region (match-beginning 0) (match-end 0)) (insert-before-markers (org-trim hd) (if empty "" " "))) - ;; FIXME: What happens when adding a new tag??? Seems OK!!! (unless (equal tags "") (move-to-column (max (current-column) (if (> org-tags-column 0) @@ -6979,7 +7145,7 @@ With prefix ARG, realign all tags in headings in the current buffer." (save-excursion (beginning-of-line 1) (if (looking-at ".*[ \t]\\(:[A-Za-z_@0-9:]+:\\)[ \t]*\\(\r\\|$\\)") - (match-string 1) + (org-match-string-no-properties 1) ""))) (defun org-get-buffer-tags () @@ -6989,7 +7155,7 @@ With prefix ARG, realign all tags in headings in the current buffer." (goto-char (point-min)) (while (re-search-forward "[ \t]:\\([A-Za-z_@0-9:]+\\):[ \t\r\n]" nil t) (mapc (lambda (x) (add-to-list 'tags x)) - (org-split-string (match-string 1) ":")))) + (org-split-string (org-match-string-no-properties 1) ":")))) (mapcar 'list tags))) ;;; Link Stuff @@ -7029,7 +7195,7 @@ optional argument IN-EMACS is non-nil, Emacs will visit the file." (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) + (if (string-match org-link-re-with-space link) (setq type (match-string 1 link) path (match-string 2 link)) (setq type "thisfile" @@ -7047,8 +7213,8 @@ optional argument IN-EMACS is non-nil, Emacs will visit the file." (save-excursion (skip-chars-backward - (concat (if org-allow-space-in-links "^" "^ ") - org-non-link-chars)) + (concat "^[]" org-non-link-chars + (if org-allow-space-in-plain-links " " ""))) (when (or (looking-at org-link-regexp) (and (re-search-forward org-link-regexp (point-at-eol) t) (<= (match-beginning 0) pos) @@ -7071,19 +7237,7 @@ optional argument IN-EMACS is non-nil, Emacs will visit the file." (setq type "camel" path (match-string 0)) (if (equal (char-before) ?*) (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 - (condition-case nil - (progn (outline-end-of-subtree) (max pos (point))) - (error (end-of-line 1) (point)))) - t) - (setq type (match-string 1) - path (match-string 2))))) + (throw 'match t))) (unless path (error "No link found")) ;; Remove any trailing spaces in path @@ -7242,7 +7396,7 @@ in all files." (if (or (org-search-not-link re0 nil t) (org-search-not-link re1 nil t) (org-search-not-link re2 nil t) - (org-search-not-link re2a nil t) ;; FIXME: Right place??? + (org-search-not-link re2a nil t) (org-search-not-link re3 nil t) (org-search-not-link re4 nil t) (org-search-not-link re5 nil t) @@ -7692,8 +7846,8 @@ For file links, arg negates `org-context-in-file-links'." msgnum 'message-id)) (wl-message-entity (elmo-msgdb-overview-get-entity msgnum (wl-summary-buffer-msgdb))) - (author (wl-summary-line-from)) ; FIXME: how to get author name? - (subject "???")) ; FIXME: How to get subject of email? + (author (wl-summary-line-from)) ; FIXME: correct? + (subject "???")) ; FIXME: (setq message-id (org-remove-angle-brackets message-id)) (setq cpltxt (concat author " on: " subject)) (setq link (org-make-link "wl:" wl-summary-buffer-folder-name @@ -7872,7 +8026,7 @@ For file links, arg negates `org-context-in-file-links'." (defun org-make-link-string (link &optional description) "Make a link with brackets, consisting of LINK and DESCRIPTION." - (if org-old-link-style + (if (eq org-link-style 'bracket) (concat description "\n" link) (if (stringp description) ;; Remove brackets from the description, they are fatal. @@ -7882,7 +8036,6 @@ For file links, arg negates `org-context-in-file-links'." (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.") @@ -7982,7 +8135,7 @@ is in the current directory or below." (>= (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 desc (if (match-end 3) (org-match-string-no-properties 3))) (setq link (read-string "Link: " (org-match-string-no-properties 1)))) (complete-file ;; Completing read for file names. @@ -7992,12 +8145,12 @@ is in the current directory or below." ((equal complete-file '(16)) (setq link (org-make-link "file:" - (abbreviate-file-name (expand-file-name link))))) + (abbreviate-file-name (expand-file-name file))))) ((string-match (concat "^" (regexp-quote pwd) "\\(.+\\)") - (expand-file-name link)) + (expand-file-name file)) (setq link (org-make-link - "file:" (match-string 1 (expand-file-name link))))) - (t (setq link (org-make-link "file:" link)))))) + "file:" (match-string 1 (expand-file-name file))))) + (t (setq link (org-make-link "file:" file)))))) (t ;; Read link, with completion for stored links. (setq link (completing-read @@ -8025,15 +8178,6 @@ is in the current directory or below." (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)) @@ -8407,6 +8551,8 @@ This is being used to correctly align a single field after TAB or RET.") This is being used to correctly align a single field after TAB or RET.") (defvar org-last-recalc-line nil) +(defconst org-narrow-column-arrow "=>" + "Used as display property in narrowed table columns.") (defun org-table-align () "Align the table at point by aligning all vertical bars." @@ -8500,7 +8646,9 @@ This is being used to correctly align a single field after TAB or RET.") (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))))) + (add-text-properties (- f1 2) f1 + (list 'display org-narrow-column-arrow) + 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 @@ -8551,6 +8699,9 @@ This is being used to correctly align a single field after TAB or RET.") (move-marker org-table-aligned-begin-marker (point)) (insert new) (move-marker org-table-aligned-end-marker (point)) + (when (and orgtbl-mode (not (eq major-mode 'org-mode))) + (goto-char org-table-aligned-begin-marker) + (while (org-hide-wide-columns org-table-aligned-end-marker))) ;; Try to move to the old location (approximately) (goto-line linepos) (set-window-start (selected-window) winstart 'noforce) @@ -8568,10 +8719,15 @@ 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) + '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)))))) + (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) @@ -8604,10 +8760,7 @@ With argument TABLE-TYPE, go to the end of a table.el-type table." Optional argument NEW may specify text to replace the current field content." (cond ((and (not new) org-table-may-need-update)) ; Realignment will happen anyway - ((org-at-table-hline-p) - ;; FIXME: I used to enforce realign here, but I think this is not needed. - ;; (setq org-table-may-need-update t) - ) + ((org-at-table-hline-p)) ((and (not new) (or (not (equal (marker-buffer org-table-aligned-begin-marker) (current-buffer))) @@ -8618,7 +8771,7 @@ Optional argument NEW may specify text to replace the current field content." (t ;; realign the current field, based on previous full realign (let* ((pos (point)) s (col (org-table-current-column)) - (num (nth (1- col) org-table-last-alignment)) + (num (if (> col 0) (nth (1- col) org-table-last-alignment))) l f n o e) (when (> col 0) (skip-chars-backward "^|\n") @@ -9327,26 +9480,38 @@ blank, and the content is appended to the field above." (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-edit-field (arg) + "Edit table field in a different window. +This is mainly useful for fields that contain hidden parts. +When called with a \\[universal-argument] prefix, just make the full field visible so that +it can be edited in place." + (interactive "P") + (if arg + (let ((b (save-excursion (skip-chars-backward "^|") (point))) + (e (save-excursion (skip-chars-forward "^|\r\n") (point)))) + (remove-text-properties b e '(org-cwidth t invisible t + display t intangible t)) + (if (and (boundp 'font-lock-mode) font-lock-mode) + (font-lock-fontify-block))) + (let ((pos (move-marker (make-marker) (point))) + (field (org-table-get-field)) + (cw (current-window-configuration)) + p) + (switch-to-buffer-other-window "*Org tmp*") + (erase-buffer) + (insert "#\n# Edit field and finish with C-c C-c\n#\n") + (org-mode) + (goto-char (setq p (point-max))) + (insert (org-trim field)) + (remove-text-properties p (point-max) + '(invisible t org-cwidth t display t + intangible t)) + (goto-char p) + (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. @@ -9357,7 +9522,8 @@ the table and kill the editing buffer." (cb (current-buffer)) text) (goto-char (point-min)) - (while (re-search-forward "[ \t]*\n[ \t]*" nil t) + (while (re-search-forward "^#.*\n?" nil t) (replace-match "")) + (while (re-search-forward "\\([ \t]*\n[ \t]*\\)+" nil t) (replace-match " ")) (setq text (org-trim (buffer-string))) (set-window-configuration cw) @@ -9412,7 +9578,6 @@ The return value is a list of lines, without newlines at the end." (setq lines (push line lines))) (nreverse lines))) -;; FIXME: I think I can make this more efficient (defun org-split-string (string &optional separators) "Splits STRING into substrings at SEPARATORS. No empty strings are returned if there are matches at the beginning @@ -9751,13 +9916,13 @@ expected, for the other actions only a single column number is needed." ((eq action 'swap) (setq col1 (car columns) col2 (nth 1 columns) sc1 (int-to-string col1) sc2 (int-to-string col2)) - ;; Hopefully, ZqZ will never be a name in a table... FIXME: - (org-table-replace-in-formulas list sc1 "ZqZ") + ;; Hopefully, ZqZtZ will never be a name in a table + (org-table-replace-in-formulas list sc1 "ZqZtZ") (org-table-replace-in-formulas list sc2 sc1) - (org-table-replace-in-formulas list "ZqZ" sc2) - (if (assoc sc1 list) (setcar (assoc sc1 list) "ZqZ")) + (org-table-replace-in-formulas list "ZqZtZ" sc2) + (if (assoc sc1 list) (setcar (assoc sc1 list) "ZqZtZ")) (if (assoc sc2 list) (setcar (assoc sc2 list) sc1)) - (if (assoc "ZqZ" list) (setcar (assoc "ZqZ" list) sc2))) + (if (assoc "ZqZtZ" list) (setcar (assoc "ZqZtZ" list) sc2))) (t (error "Invalid action in `org-table-modify-formulas'"))) (if list (org-table-store-formulas list)))) @@ -10337,20 +10502,6 @@ With prefix ARG, apply the new formulas to the table." ;; active, this binding is ignored inside tables and replaced with a ;; modified self-insert. -(defcustom orgtbl-optimized (eq org-enable-table-editor 'optimized) - "Non-nil means, use the optimized table editor version for `orgtbl-mode'. -In the optimized version, the table editor takes over all simple keys that -normally just insert a character. In tables, the characters are inserted -in a way to minimize disturbing the table structure (i.e. in overwrite mode -for empty fields). Outside tables, the correct binding of the keys is -restored. - -The default for this option is t if the optimized version is also used in -Org-mode. See the variable `org-enable-table-editor' for details. Changing -this variable requires a restart of Emacs to become effective." - :group 'org-table - :type 'boolean) - (defvar orgtbl-mode nil "Variable controlling `orgtbl-mode', a minor mode enabling the `org-mode' table editor in arbitrary modes.") @@ -10390,13 +10541,29 @@ table editor in arbitrary modes.") (if auto-fill-inhibit-regexp (concat "\\([ \t]*|\\|" auto-fill-inhibit-regexp) "[ \t]*|")) + (org-add-to-invisibility-spec '(org-cwidth . nil)) (easy-menu-add orgtbl-mode-menu) (run-hooks 'orgtbl-mode-hook)) (setq auto-fill-inhibit-regexp org-old-auto-fill-inhibit-regexp) + (org-cleanup-narrow-column-properties) + (org-remove-from-invisibility-spec '(org-cwidth . nil)) (remove-hook 'before-change-functions 'org-before-change-function t) (easy-menu-remove orgtbl-mode-menu) (force-mode-line-update 'all)))) +(defun org-cleanup-narrow-column-properties () + "Remove all properties related to narrow-column invisibility." + (let ((s 1)) + (while (setq s (text-property-any s (point-max) + 'display org-narrow-column-arrow)) + (remove-text-properties s (1+ s) '(display t))) + (setq s 1) + (while (setq s (text-property-any s (point-max) 'org-cwidth 1)) + (remove-text-properties s (1+ s) '(org-cwidth t))) + (setq s 1) + (while (setq s (text-property-any s (point-max) 'invisible 'org-cwidth)) + (remove-text-properties s (1+ s) '(invisible t))))) + ;; Install it as a minor mode. (put 'orgtbl-mode :included t) (put 'orgtbl-mode :menu-tag "Org Table Mode") @@ -10489,8 +10656,8 @@ to execute outside of tables." ;; some standard editing functions (org-remap orgtbl-mode-map 'self-insert-command 'orgtbl-self-insert-command - 'delete-char 'orgtbl-delete-char - 'delete-backward-char 'orgtbl-delete-backward-char) + 'delete-char 'org-delete-char + 'delete-backward-char 'org-delete-backward-char) (define-key orgtbl-mode-map "|" 'org-force-self-insert)) (easy-menu-define orgtbl-mode-menu orgtbl-mode-map "OrgTbl menu" '("OrgTbl" @@ -10540,11 +10707,12 @@ to execute outside of tables." )) t) -(defun orgtbl-tab () +(defun orgtbl-tab (arg) "Justification and field motion for `orgtbl-mode'." - (interactive) - (org-table-justify-field-maybe) - (org-table-next-field)) + (interactive "P") + (if arg (org-table-edit-field t) + (org-table-justify-field-maybe) + (org-table-next-field))) (defun orgtbl-ret () "Justification and field motion for `orgtbl-mode'." @@ -10585,43 +10753,6 @@ overwritten, and the table is not marked as requiring realignment." (interactive "p") (self-insert-command N)) -(defun orgtbl-delete-backward-char (N) - "Like `delete-backward-char', insert whitespace at field end in tables. -When deleting backwards, in tables this function will insert whitespace in -front of the next \"|\" separator, to keep the table aligned. The table will -still be marked for re-alignment, because a narrow field may lead to a -reduced column width." - (interactive "p") - (if (and (org-at-table-p) - (eq N 1) - (string-match "|" (buffer-substring (point-at-bol) (point))) - (looking-at ".*?|")) - (let ((pos (point))) - (backward-delete-char N) - (skip-chars-forward "^|") - (insert " ") - (goto-char (1- pos))) - (delete-backward-char N))) - -(defun orgtbl-delete-char (N) - "Like `delete-char', but insert whitespace at field end in tables. -When deleting characters, in tables this function will insert whitespace in -front of the next \"|\" separator, to keep the table aligned. The table -will still be marked for re-alignment, because a narrow field may lead to -a reduced column width." - (interactive "p") - (if (and (org-at-table-p) - (not (bolp)) - (not (= (char-after) ?|)) - (eq N 1)) - (if (looking-at ".*?|") - (let ((pos (point))) - (replace-match (concat - (substring (match-string 0) 1 -1) - " |")) - (goto-char pos))) - (delete-char N))) - ;;; Exporting (defconst org-level-max 20) @@ -10979,16 +11110,24 @@ translations. There is currently no way for users to extend this.") (goto-char (point-min)) (while (re-search-forward "^#.*?\\(<<<?[^>\r\n]+>>>?\\).*" nil t) (replace-match "\\1(INVISIBLE)")) - ;; Find matches for radio targets and turn them into links + ;; Find matches for radio targets and turn them into internal links (goto-char (point-min)) (when re-radio (while (re-search-forward re-radio nil t) (replace-match "\\1[[\\2]]"))) ;; Find all links that contain a newline and put them into a single line (goto-char (point-min)) - (while (re-search-forward "\\(\\[\\[[^]]*?\\)[ \t]*\n[ \t]*\\([^]]*\\]\\]\\)" nil t) - (replace-match "\\1 \\2") + (while (re-search-forward "\\(\\(\\[\\|\\]\\)\\[[^]]*?\\)[ \t]*\n[ \t]*\\([^]]*\\]\\(\\[\\|\\]\\)\\)" nil t) + (replace-match "\\1 \\3") (goto-char (match-beginning 0))) + ;; Normalize links: Convert angle and plain links into bracket links + (goto-char (point-min)) + (while (re-search-forward org-external-link-maybe-brackets nil t) + (replace-match + (concat (if (match-end 1) (match-string 1) "[[") + (match-string 3) ":" (match-string 4) + (if (match-end 5) (match-string 5) "]]")) t t)) + ;; Remove comments (goto-char (point-min)) (while (re-search-forward "^#.*\n?" nil t) @@ -11192,7 +11331,7 @@ underlined headlines. The default is 3." (if todo (throw 'exit t)))))))) ;; FIXME: Try to handle <b> and <i> as faces via text properties. -;; FIXME: Can I implement *bold*,/italic/ and _underline_ for ASCII export? +;; We could also implement *bold*,/italic/ and _underline_ for ASCII export (defun org-html-expand-for-ascii (line) "Handle quoted HTML for ASCII export." (if org-export-html-expand @@ -11445,6 +11584,7 @@ headlines. The default is 3. Lower levels will become bulleted lists." table-open type table-buffer table-orig-buffer ind start-is-num starter + rpl path desc desc1 desc2 link ) (message "Exporting...") @@ -11608,24 +11748,6 @@ headlines. The default is 3. Lower levels will become bulleted lists." (org-solidify-link-text (match-string 1 line)) "\" class=\"target\">" (match-string 1 line) "@</a> ") t t line))))) - ;; Replace internal links - (while (string-match org-bracket-link-regexp line) - (setq line (replace-match - (concat - "@<a href=\"#" - (org-solidify-link-text (match-string 1 line) target-alist) - "\">" - (match-string (if (match-end 3) 3 1) line) - "@</a>") - t t line))) - - ;; Protect the external links - (setq start 0) - (while (string-match org-link-maybe-angles-regexp line start) - (setq start (match-end 0)) - (setq line (replace-match - (concat "\000" (match-string 1 line) "\000") - t t line))) ;; replace "&" by "&", "<" and ">" by "<" and ">" ;; handle @<..> HTML tags (replace "@>..<" by "<..>") @@ -11633,19 +11755,27 @@ headlines. The default is 3. Lower levels will become bulleted lists." ;; Format the links (setq start 0) - (while (string-match org-protected-link-regexp line start) - (setq start (- (match-end 0) 2)) - (setq type (match-string 1 line)) + (while (string-match org-bracket-link-analytic-regexp line start) + (setq start (match-beginning 0)) + (setq type (if (match-end 2) (match-string 2 line) "internal")) + (setq path (match-string 3 line)) + (setq desc1 (if (match-end 5) (match-string 5 line)) + desc2 (if (match-end 2) (concat type ":" path) path) + desc (or desc1 desc2)) (cond + ((equal type "internal") + (setq rpl + (concat + "<a href=\"#" + (org-solidify-link-text path target-alist) + "\">" desc "</a>"))) ((member type '("http" "https" "ftp" "mailto" "news")) ;; standard URL - (setq line (replace-match - ; "<a href=\"\\1:\\2\"><\\1:\\2></a>" - "<a href=\"\\1:\\2\">\\1:\\2</a>" - nil nil line))) + (setq link (concat type ":" path)) + (setq rpl (concat "<a href=\"" link "\">" desc "</a>"))) ((string= type "file") ;; FILE link - (let* ((filename (match-string 2 line)) + (let* ((filename path) (abs-p (file-name-absolute-p filename)) (thefile (if abs-p (expand-file-name filename) filename)) (thefile (save-match-data @@ -11655,17 +11785,14 @@ headlines. The default is 3. Lower levels will become bulleted lists." (file-is-image-p (save-match-data (string-match (org-image-file-name-regexp) thefile)))) - (setq line (replace-match - (if (and org-export-html-inline-images - file-is-image-p) - (concat "<img src=\"" thefile "\"/>") - (concat "<a href=\"" thefile "\">\\1:\\2</a>")) - nil nil line)))) - + (setq rpl (if (and org-export-html-inline-images + file-is-image-p) + (concat "<img src=\"" thefile "\"/>") + (concat "<a href=\"" thefile "\">" desc "</a>"))))) ((member type '("bbdb" "vm" "wl" "mhe" "rmail" "gnus" "shell")) - (setq line (replace-match - "<i><\\1:\\2></i>" nil nil line))))) - + (setq rpl (concat "<i><" type ":" path "></i>")))) + (setq line (replace-match rpl t t line) + start (+ start (length rpl)))) ;; TODO items (if (and (string-match org-todo-line-regexp line) (match-beginning 2)) @@ -12412,6 +12539,8 @@ a time), or the day by one (if it does not contain a time)." (define-key org-mode-map "\C-c\C-xt" 'org-insert-export-options-template) (define-key org-mode-map "\C-c:" 'org-toggle-fixed-width-section) (define-key org-mode-map "\C-c\C-xh" 'org-export-as-html) +(define-key org-mode-map "\C-c\C-xx" 'org-export-as-xml) +(define-key org-mode-map "\C-c\C-x\C-x" 'org-export-as-xml) (define-key org-mode-map "\C-c\C-xb" 'org-export-as-html-and-open) (define-key org-mode-map "\C-c\C-x\C-b" 'org-export-as-html-and-open) @@ -12428,14 +12557,19 @@ If the cursor is in a table looking at whitespace, the whitespace is overwritten, and the table is not marked as requiring realignment." (interactive "p") (if (and (org-table-p) - (or - (and org-table-auto-blank-field - (member last-command - '(org-cycle org-return org-shifttab org-ctrl-c-ctrl-c)) - (org-table-blank-field)) - t) + (progn + ;; check if we blank the field, and if that triggers align + (and org-table-auto-blank-field + (member last-command + '(org-cycle org-return org-shifttab org-ctrl-c-ctrl-c)) + (if (or (equal (char-after) ?\ ) (looking-at "[^|\n]* |")) + ;; got extra space, this field does not determine column width + (let (org-table-may-need-update) (org-table-blank-field)) + ;; no extra space, this field may determine column width + (org-table-blank-field))) + t) (eq N 1) - (looking-at "[^|\n]* +|")) + (looking-at "[^|\n]* |")) (let (org-table-may-need-update) (goto-char (1- (match-end 0))) (delete-backward-char 1) @@ -12444,45 +12578,51 @@ overwritten, and the table is not marked as requiring realignment." (setq org-table-may-need-update t) (self-insert-command N))) -;; FIXME: -;; The following two functions might still be optimized to trigger -;; re-alignment less frequently. - (defun org-delete-backward-char (N) "Like `delete-backward-char', insert whitespace at field end in tables. When deleting backwards, in tables this function will insert whitespace in front of the next \"|\" separator, to keep the table aligned. The table will -still be marked for re-alignment, because a narrow field may lead to a -reduced column width." +still be marked for re-alignment if the field did fill the entire column, +because, in this case the deletion might narrow the column." (interactive "p") (if (and (org-table-p) (eq N 1) (string-match "|" (buffer-substring (point-at-bol) (point))) (looking-at ".*?|")) - (let ((pos (point))) + (let ((pos (point)) + (noalign (looking-at "[^|\n\r]* |")) + (c org-table-may-need-update)) (backward-delete-char N) (skip-chars-forward "^|") (insert " ") - (goto-char (1- pos))) + (goto-char (1- pos)) + ;; noalign: if there were two spaces at the end, this field + ;; does not determine the width of the column. + (if noalign (setq org-table-may-need-update c))) (backward-delete-char N))) (defun org-delete-char (N) "Like `delete-char', but insert whitespace at field end in tables. When deleting characters, in tables this function will insert whitespace in -front of the next \"|\" separator, to keep the table aligned. The table -will still be marked for re-alignment, because a narrow field may lead to -a reduced column width." +front of the next \"|\" separator, to keep the table aligned. The table will +still be marked for re-alignment if the field did fill the entire column, +because, in this case the deletion might narrow the column." (interactive "p") (if (and (org-table-p) (not (bolp)) (not (= (char-after) ?|)) (eq N 1)) (if (looking-at ".*?|") - (let ((pos (point))) + (let ((pos (point)) + (noalign (looking-at "[^|\n\r]* |")) + (c org-table-may-need-update)) (replace-match (concat (substring (match-string 0) 1 -1) " |")) - (goto-char pos))) + (goto-char pos) + ;; noalign: if there were two spaces at the end, this field + ;; does not determine the width of the column. + (if noalign (setq org-table-may-need-update c)))) (delete-char N))) ;; How to do this: Measure non-white length of current string @@ -12691,7 +12831,7 @@ If the cursor is on a #+TBLFM line, re-apply the formulae to the table." (fboundp org-finish-function)) (funcall org-finish-function)) ; ((and (boundp 'remember-buffer) (equal (buffer-name) remember-buffer)) -; (remember-buffer)) ;; FIXME: remove this?????? +; (remember-buffer)) ;; FIXME: can we remove this?????? ((org-on-target-p) (org-update-radio-target-regexp)) ((org-on-heading-p) (org-set-tags arg)) ((org-at-table.el-p) @@ -12901,7 +13041,7 @@ See the individual commands for more information." ["Extract Visible Text" org-export-copy-visible t] ["HTML" org-export-as-html t] ["HTML and Open" org-export-as-html-and-open t] -; ["OPML" org-export-as-opml nil] + ["XML (XOXO)" org-export-as-xml t] "--" ["iCalendar this file" org-export-icalendar-this-file t] ["iCalendar all agenda files" org-export-icalendar-all-agenda-files @@ -13343,6 +13483,114 @@ Show the heading too, if it is currently invisible." ;; Experimental code +(defun org-upgrade-old-links (&optional broken-only) + "Transfer old <...> style links to new [[...]] style links. +With arg BROKEN-ONLY, fix only the links that contain space characters +and therefore have stopped working in this new version." + (interactive "P") + (save-excursion + (goto-char (point-min)) + (let ((re (concat "\\([^[]\\)<\\(" + "\\(" (mapconcat 'identity org-link-types "\\|") + "\\):" + "[^" org-non-link-chars "]+\\)>")) + l1 l2) + (while (re-search-forward re nil t) + (setq l1 (match-string 2) + l2 (save-match-data + (org-link-escape (match-string 2)))) + (when (or (not broken-only) + (save-match-data (string-match " " l1))) + (if (equal l1 l2) + (replace-match (concat (match-string 1) "[[" l1 "]]") t t) + (replace-match + (concat (match-string 1) "[[" l2 "][" l1 "]]") + t t))))))) + +(defun org-export-as-xml () + "Export current buffer as XOXO XML buffer." + (interactive) + (cond ((eq org-export-xml-type 'xoxo) + (org-export-as-xoxo (current-buffer))))) + +(defun org-export-as-xoxo-insert-into (buffer &rest output) + (with-current-buffer buffer + (apply 'insert output))) + +(defun org-export-as-xoxo (&optional buffer) + "Export the org buffer as XOXO. +The XOXO buffer is named *xoxo-<source buffer name>*" + (interactive (list (current-buffer))) + ;; A quickie abstraction + + ;; Output everything as XOXO + (with-current-buffer (get-buffer buffer) + (goto-char (point-min)) ;; CD: beginning-of-buffer is not allowed. + (let* ((filename (concat (file-name-sans-extension buffer-file-name) + ".xml")) + (out (find-file-noselect filename)) + (last-level 1) + (hanging-li nil)) + ;; Check the output buffer is empty. + (with-current-buffer out (erase-buffer)) + ;; Kick off the output + (org-export-as-xoxo-insert-into out "<ol class='xoxo'>\n") + (while (re-search-forward "^\\(\\*+\\) \\(.+\\)" (point-max) 't) + (let* ((hd (match-string-no-properties 1)) + (level (length hd)) + (text (concat + (match-string-no-properties 2) + (save-excursion + (goto-char (match-end 0)) + (let ((str "")) + (catch 'loop + (while 't + (forward-line) + (if (looking-at "^[ \t]\\(.*\\)") + (setq str (concat str (match-string-no-properties 1))) + (throw 'loop str))))))))) + + ;; Handle level rendering + (cond + ((> level last-level) + (org-export-as-xoxo-insert-into out "\n<ol>\n")) + + ((< level last-level) + (dotimes (- (- last-level level) 1) + (if hanging-li + (org-export-as-xoxo-insert-into out "</li>\n")) + (org-export-as-xoxo-insert-into out "</ol>\n")) + (when hanging-li + (org-export-as-xoxo-insert-into out "</li>\n") + (setq hanging-li nil))) + + ((equal level last-level) + (if hanging-li + (org-export-as-xoxo-insert-into out "</li>\n"))) + ) + + (setq last-level level) + + ;; And output the new li + (setq hanging-li 't) + (if (equal ?+ (elt text 0)) + (org-export-as-xoxo-insert-into out "<li class='" (substring text 1) "'>") + (org-export-as-xoxo-insert-into out "<li>" text)))) + + ;; Finally finish off the ol + (dotimes (- last-level 1) + (if hanging-li + (org-export-as-xoxo-insert-into out "</li>\n")) + (org-export-as-xoxo-insert-into out "</ol>\n")) + + ;; Finish the buffer off and clean it up. + (switch-to-buffer-other-window out) + (indent-region (point-min) (point-max)) + (save-buffer) + (goto-char (point-min)) + ))) + ;; arch-tag: e77da1a7-acc7-4336-b19e-efa25af3f9fd ;;; org.el ends here +
\ No newline at end of file Binary files differ@@ -4,7 +4,7 @@ @c @setfilename ../info/org @settitle Org Mode Manual -@set VERSION 4.19a +@set VERSION 4.19b @set DATE March 2006 @dircategory Emacs @@ -311,6 +311,12 @@ MY PROJECTS -*- mode: org; -*- the file's name is. See also the variable @code{org-insert-mode-line-in-empty-file}. +If you are upgrading to version 4.20 or later from a version 4.14 or +earlier, some links may stop working. These are links containing space +characters. To make such links work again, and also to transform all +links from the old @samp{<link>} format to the new @samp{[[link]]} +format, execute once in each file: @kbd{M-x org-upgrade-old-links}. + @node Feedback, , Installation and activation, Introduction @section Feedback @cindex feedback @@ -328,6 +334,7 @@ including the version information of Emacs (@kbd{C-h v emacs-version the Org-mode related setup in @file{.emacs}. If an error occurs, a traceback can be very useful. Often a small example file helps, along with clear information about: + @enumerate @item What exactly did you do? @item What did you expect to happen? @@ -387,6 +394,7 @@ example: more text * Another top level headline @end example + @noindent Some people find the many stars too noisy and would prefer an outline that has whitespace followed by a single star as headline starters. @ref{Clean view} describes a setup to realize this. @@ -411,10 +419,12 @@ the visibility in the buffer. @kindex @key{TAB} @item @key{TAB} Rotate current subtree between the states + @example ,-> FOLDED -> CHILDREN -> SUBTREE --. '-----------------------------------' @end example + At the beginning of the buffer (or when called with @kbd{C-u}), this does the same as the command @kbd{S-@key{TAB}} below. @@ -425,10 +435,12 @@ the same as the command @kbd{S-@key{TAB}} below. @kindex S-@key{TAB} @item S-@key{TAB} Rotate the entire buffer between the states + @example ,-> OVERVIEW -> CONTENTS -> SHOW ALL --. '--------------------------------------' @end example + Note that inside tables, @kbd{S-@key{TAB}} jumps to the previous field. @cindex show all, command @@ -610,10 +622,12 @@ use the variable @code{org-agenda-custom-commands} to define fast keyboard access to specific sparse trees. These commands will then be accessible through the agenda dispatcher (@pxref{Agenda dispatcher}). For example: + @lisp (setq org-agenda-custom-commands '(("f" occur-tree "FIXME"))) @end lisp + @noindent will define the key @kbd{C-c a f} as a shortcut for creating a sparse tree matching the string @samp{FIXME}. @@ -757,6 +771,7 @@ create the above table, you would only type |Name|Phone|Age |- @end example + @noindent and then press @key{TAB} to align the table and start filling in fields. @@ -934,7 +949,14 @@ incremented during copy. This key is also used by CUA-mode @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}). +that are not fully visible (@pxref{Narrow columns}). When called with a +@kbd{C-u} prefix, just make the full field visible, so that it can be +edited in place. + +@kindex C-c @key{TAB} +@item C-c @key{TAB} +This is an alias for @kbd{C-u C-c `} to make the current field fully +visible. @kindex C-c | @item C-c | @@ -959,9 +981,11 @@ for example, Excel or database programs. If you don't like the automatic table editor because it gets in your way on lines which you would like to start with @samp{|}, you can turn it off with + @lisp (setq org-enable-table-editor nil) @end lisp + @noindent The only table command which then still works is @kbd{C-c C-c} to do a manual re-align. @@ -986,6 +1010,7 @@ will then set the width of this column to no more than this value. | 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. @@ -1001,6 +1026,7 @@ 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 @@ -1087,6 +1113,7 @@ or fixed display format, respectively, and @samp{D}, @samp{R}, @samp{F}, and @samp{S} to turn on degrees, radians, fraction and symbolic modes, respectively. In addition, you may provide a @code{printf} format specifier to reformat the final result. A few examples: + @example $1+$2 @r{Sum of first and second field} $1+$2;%.2f @r{Same, format result to two decimals} @@ -1147,6 +1174,7 @@ or if you want to be able to assign a formula to an individual field the table for special marking characters. Here is an example of a table that collects exam results of students and makes use of these features: + @example @group |---+---------+--------+--------+--------+-------+------| @@ -1297,6 +1325,7 @@ might want to use it also in other modes like text-mode or mail-mode. The minor mode Orgtbl-mode makes this possible. You can always toggle the mode with @kbd{M-x orgtbl-mode}. To turn it on by default, for example in mail mode, use + @lisp (add-hook 'mail-mode-hook 'turn-on-orgtbl) @end lisp @@ -1353,11 +1382,13 @@ links to other files, Usenet articles, emails and much more. @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: +them as clickable links. However, the general linkformat looks like +this: + @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 @@ -1365,11 +1396,13 @@ complete, Org-mode will change the display so that @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.}. +with the cursor on the link. If you place the cursor at the beginning +of end of the displayed text and press @key{BACKSPACE}, you will remove +the (invisible) bracket at that location. This makes the link incomplete +and the internals are again displayed as plain text. Inserting the +missing bracket does hide the link internal again. Finally, 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 @@ -1385,6 +1418,7 @@ 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 # <<My Target>> @end example @@ -1396,6 +1430,7 @@ 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 @@ -1436,12 +1471,13 @@ loaded into Emacs. To update the target list during editing, press @cindex completion, of CamelCase links @cindex CamelCase links, completion of -As an alternative to @samp{[[...]]} links, Org-mode also supports -CamelCase words as links. This feature is not turned on by default -because of the occasional inconsistencies this system suffers from. -To activate CamelCase words as links, and to make headline completion -offer CamelCase version of headlines, the following customization is -needed: +Org-mode also supports CamelCase words as links. This feature is not +turned on by default because of the inconsistencies this system suffers +from. It is mainly kept for backward compatibility, but the use is +deprecated. To activate CamelCase words as links, and to make headline +completion offer CamelCase version of headlines, the following +customization is needed: + @lisp (setq org-activate-camels t org-file-link-context-use-camel-case t) @@ -1464,45 +1500,43 @@ needed: @cindex SHELL links Org-mode supports links to files, websites, Usenet and email messages; -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. +and BBDB database entries. External links are URL-like locators. The +following list shows examples for each link type. @example -<http://www.astro.uva.nl/~dominik> @r{on the web} -<file:/home/dominik/images/jupiter.jpg> @r{file, absolute path} -<file:papers/last.pdf> @r{file, relative path} -<news:comp.emacs> @r{Usenet link} -<mailto:adent@@galaxy.net> @r{Mail link} -<vm:folder> @r{VM folder link} -<vm:folder#id> @r{VM message link} -<vm://myself@@some.where.org/folder#id> @r{VM on remote machine} -<wl:folder> @r{WANDERLUST folder link} -<wl:folder#id> @r{WANDERLUST message link} -<mhe:folder> @r{MH-E folder link} -<mhe:folder#id> @r{MH-E message link} -<rmail:folder> @r{RMAIL folder link} -<rmail:folder#id> @r{RMAIL message link} -<gnus:group> @r{GNUS group link} -<gnus:group#id> @r{GNUS article link} -<bbdb:Richard Stallman> @r{BBDB link} -<shell:ls *.org>@footnote{Note that @samp{<} and @samp{>} cannot be part of a link, and therefore of a shell command. If you need redirection, use @@@{ and @@@} instead.} @r{A shell command} +http://www.astro.uva.nl/~dominik @r{on the web} +file:/home/dominik/images/jupiter.jpg @r{file, absolute path} +file:papers/last.pdf @r{file, relative path} +news:comp.emacs @r{Usenet link} +mailto:adent@@galaxy.net @r{Mail link} +vm:folder @r{VM folder link} +vm:folder#id @r{VM message link} +vm://myself@@some.where.org/folder#id @r{VM on remote machine} +wl:folder @r{WANDERLUST folder link} +wl:folder#id @r{WANDERLUST message link} +mhe:folder @r{MH-E folder link} +mhe:folder#id @r{MH-E message link} +rmail:folder @r{RMAIL folder link} +rmail:folder#id @r{RMAIL message link} +gnus:group @r{GNUS group link} +gnus:group#id @r{GNUS article link} +bbdb:Richard Stallman @r{BBDB link} +shell:ls *.org@footnote{Note that @samp{<} and @samp{>} cannot be part of a link, and therefore of a shell command. If you need redirection, use @@@{ and @@@} instead.} @r{A shell command} @end example -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. +A link should be enclosed in double brackets and may contain a +descriptive text to be displayed instead of the url (@pxref{Link +format}), for example: -To display a descriptive text instead of the URL, enclose the link into -double brackets and add the descriptive text like this: @example -[[<http://www.gnu.org/software/emacs/>][GNU Emacs]] +[[http://www.gnu.org/software/emacs/][GNU Emacs]] @end example -@noindent Links inserted with @kbd{C-c C-l} automatically use the double -bracket format (@pxref{Managing links}). +@cindex angular brackets, around links +@cindex plain text external links +Org-mode also finds external links in the normal text and activates them +as links. Plain text links cannot contain spaces. To remove +ambiguities about the end of the link, enclose them in angular brackets. @node Managing links, Search Options, External links, Hyperlinks @section Managing links @@ -1529,41 +1563,51 @@ activation}. @kindex C-c C-l @cindex link completion -@cindex file name completion @cindex completion, of links -@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 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. +all links stored during the current session can be accessed. The link +will be formatted as given in the variable @code{org-link-format} and +inserted into the buffer, along with a descriptive text. Note that you +don't have to use this command to insert a link. Links in Org-mode are +plain text, and you can type or paste them straight into the buffer. +By using this command, the links are automatically enclosed in double +brackets, and you will be asked for the optional descriptive text. + +@kindex C-u C-c C-l +@cindex file name completion +@cindex completion, of file names +@item C-u C-c C-l +When @kbd{C-c C-l} is called with a @kbd{C-u} prefix argument, a link to +a file will be inserted and you may use file name completion to select +the name of the file. The path to the file is inserted relative to the +directory of the current org file, if the linked file is in the current +directory or in a subdirectory of it. Otherwise an absolute path, if +possible with @samp{~/} for your home directory is used. You can force +an absolute path with two @kbd{C-u} prefixes. + +@item C-c C-l @r{with cursor on existing link} +When the cursor is on an existing link, @kbd{C-c C-l} allows to edit the +link and description parts of the link. @cindex following links @kindex C-c C-o @item C-c C-o 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 -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 -non-text files. Classification of files is based on file extension -only. See option @code{org-file-apps}. If there is no link at point, -the current subtree will be searched for one. If you want to override -the default application and visit the file with Emacs, use a @kbd{C-u} -prefix. If the cursor is on a time stamp, it compiles the agenda for -that date. - -@strong{IMPORTANT}: Be careful not to use any dangerous commands in a -shell link. +@command{browse-url-at-point}), run vm/mh-e/wanderlust/rmail/gnus/bbdb +for the corresponding links, and execute the command in a shell link. +When the cursor is on an internal link, this commands runs the +corresponding search. When the cursor is on a TAGS list in a headline, +it creates the corresponding TAGS view. If the cursor is on a time +stamp, it compiles the agenda for that date. Furthermore, it will visit +text files in @samp{file:} links with Emacs and select a suitable +application for non-text files. Classification of files is based on +file extension only. See option @code{org-file-apps}. If you want to +override the default application and visit the file with Emacs, use a +@kbd{C-u} prefix. @kindex mouse-2 @kindex mouse-1 @@ -1602,12 +1646,14 @@ particular location in the file when following a link. This can be a line number or a search option after a double@footnote{For backward compatibility, line numbers can also follow a single colon.} colon. For example: + @example -<file:~/code/main.c::255> -<file:~/xx.org::My Target> -<file:~/xx.org::*My Target> -<file:~/xx.org::/regexp/> +[[file:~/code/main.c::255]] +[[file:~/xx.org::My Target]] +[[file:~/xx.org::*My Target]] +[[file:~/xx.org::/regexp/]] @end example + @noindent Here is what these options do. @table @code @@ -1672,6 +1718,7 @@ journal entries, you could use: '((?t "* TODO %?\n %i\n %a" "~/org/TODO.org") (?j "* %U %?\n\n %i\n %a" "~/org/JOURNAL.org"))) @end example + @noindent In these entries, the character specifies how to select the template, the first string specifies the template, and the second string specifies a default file (overruling @code{org-default-notes-file}) as a @@ -1683,7 +1730,9 @@ for a key to select the template and then prepare the buffer like * TODO <file:link to where you called remember> @end example + @noindent or + @example * [2006-03-21 Tue 15:37] @@ -1767,10 +1816,12 @@ The most important commands to work with TODO entries are: @cindex cycling, of TODO states @item C-c C-t Rotate the TODO state of the current item between + @example ,-> (unmarked) -> TODO -> DONE --. '--------------------------------' @end example + The same rotation can also be done ``remotely'' from the timeline and agenda buffers with the @kbd{t} command key (@pxref{Agenda commands}). @kindex C-c C-v @@ -1799,9 +1850,11 @@ agenda, customize the variable @code{org-agenda-include-all-todo}. @cindex logging, of progress If you want to keep track of @emph{when} a certain TODO item was finished, turn on logging with + @lisp (setq org-log-done t) @end lisp + @noindent Then each time you turn a TODO entry into DONE using either @kbd{C-c C-t} in the Org-mode buffer or @kbd{t} in the agenda buffer, a line @@ -2176,7 +2229,7 @@ Choose date in calendar (only if nothing typed into minibuffer). @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 +excellent way is to assign @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. @@ -2203,6 +2256,7 @@ well. For example, in the list ** 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 @@ -2283,6 +2337,7 @@ 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: + @itemize @bullet @item an @emph{agenda} that is like a calendar and shows information @@ -2294,6 +2349,7 @@ action items, and a @emph{tags view} that shows information based on the tags associated with headlines in the outline tree. @end itemize + @noindent The extracted information is displayed in a special @emph{agenda buffer}. This buffer is read-only, but provides commands to visit the @@ -2338,6 +2394,7 @@ Remove current file from the list of agenda files. @item C-, Cycle through agenda file list, visiting one file after the other. @end table + @noindent The Org menu contains the current list of files and can be used to visit any of them. @@ -2377,6 +2434,7 @@ Custom commands are configured in the variable @code{org-agenda-custom-commands}. You can customize this variable, for example by pressing @kbd{C-c a C}. You can also directly set it with Emacs Lisp in @file{.emacs}. For example: + @lisp (setq org-agenda-custom-commands '(("w" todo "WAITING") @@ -2384,6 +2442,7 @@ with Emacs Lisp in @file{.emacs}. For example: ("U" tags-tree "+BOSS-URGENT") ("f" occur-tree "\\<FIXME\\>"))) @end lisp + @noindent will define @kbd{C-c a w} as a global search for TODO entries with @samp{WAITING} as the TODO keyword, @kbd{C-c a u} as a global tags search for headlines marked @samp{:BOSS:} but not @@ -2430,9 +2489,11 @@ commands}. In the agenda buffer, each entry is preceded by a @emph{category}, which is derived from the file name. The category can also be set with a special line anywhere in the buffer, looking like this: + @example #+CATEGORY: Thesis @end example + If there are several such lines in a file, each specifies the category for the text below it (but the first category also applies to any text before the first CATEGORY line). The display in the agenda buffer looks @@ -2505,7 +2566,6 @@ agenda, you only need to customize the variable @lisp (setq org-agenda-include-diary t) @end lisp -@noindent @noindent After that, everything will happen automatically. All diary entries including holidays, anniversaries etc will be included in the @@ -2618,8 +2678,8 @@ Show a time-sorted view of the org file, with all time-stamped items. When called with a @kbd{C-u} prefix, all unfinished TODO entries (scheduled or not) are also listed under the current date. @end table -@noindent +@noindent The commands available in the timeline buffer are listed in @ref{Agenda commands}. @@ -2876,9 +2936,11 @@ In the exported version, the first 3 outline levels will become headlines, defining a general document structure. Additional levels will be exported as itemized lists. If you want that transition to occur at a different level, specify it with a prefix argument. For example, + @example @kbd{C-1 C-c C-x a org-export-as-ascii} @end example + @noindent creates only top level headlines and does the rest as items. Lines starting with @samp{#} and subtrees starting with the word @samp{COMMENT} @@ -2915,9 +2977,11 @@ In the exported version, the first 3 outline levels will become headlines, defining a general document structure. Additional levels will be exported as itemized lists. If you want that transition to occur at a different level, specify it with a prefix argument. For example, + @example @kbd{C-2 C-c C-x b} @end example + @noindent creates two levels of headings and does the rest as items. @@ -3007,6 +3071,7 @@ correct is to type @samp{#+} and then use @kbd{M-@key{TAB}} completion #+TEXT: Several lines may be given. #+OPTIONS: H:2 num:t toc:t \n:nil @:t ::t |:t ^:t *:nil TeX:t @end example + @noindent The OPTIONS line is a compact form to specify export settings. Here you can: @@ -3227,6 +3292,7 @@ the buffer) #+STARTUP: showstars #+STARTUP: hidestars @end example + @noindent Press @kbd{C-c C-c} with the cursor in a @samp{STARTUP} line to activate the modifications. @@ -3340,6 +3406,23 @@ turn it on for all @file{README} files?} (add-to-list 'auto-mode-alist '("README$" . org-mode)) @end example +@item @b{Some of my links stopped working after I upgraded to a version +4.20 or later. Why is this, and how can I fix it?}@* The newer versions of +Org-mode have a better link system and no longer allow unescaped space +characters as part of a link. To fix these links, and also to move all +@samp{<link>} style links to the new @samp{[[link]]} system, execute +once in each Org-mode file: @kbd{M-x org-upgrade-old-links}. + +@item @b{I really like the old style links with angular brackets +better. Please give them back to me, don't tell me it is not +possible!}@* Would I let you down like that? If you must (even if I +don't understand why), you can do this +@lisp +(setq org-allow-space-in-plain-links t + org-link-style 'plain + org-link-format "<%s>") +@end lisp + @item @b{All these stars are driving me mad, I just find the Emacs outlines unreadable. Can't you just put white space and a single star as a starter for headlines?}@* @@ -3501,11 +3584,13 @@ packages along with Org-mode, configure the variable @code{org-CUA-compatible}. When set, Org-mode will move the following keybindings in org-mode files, and in the agenda buffer (but not during date selection). + @example S-UP -> M-p S-DOWN -> M-n S-LEFT -> M-- S-RIGHT -> M-+ S-RET -> C-S-RET @end example + Yes, these are unfortunately more difficult to remember. If you want to have other replacement keys, look at the variable @code{org-disputed-keys}. @@ -3589,12 +3674,13 @@ Remember. Pavel Chalmoviansky influenced the agenda treatment of items with specified time. @item -Sacha Chua suggested to copy linking code from Planner (we did take -some). +Sacha Chua suggested to copy some linking code from Planner. @item Christian Egli converted the documentation into TeXInfo format, patched CSS formatting into the HTML exporter, and inspired the agenda. @item +Nic Ferrier contributed mailcap and XML support. +@item Kai Grossjohann pointed out key-binding conflicts caused by Org-mode. @item Stefan Monnier provided a patch to keep the Emacs-Lisp compiler happy. @@ -3630,10 +3716,12 @@ Chris Wallace provided a patch implementing the @samp{QUOTE} keyword. David Wainberg suggested archiving, and improvements to the linking system. @item -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. +John Wiegley wrote @file{emacs-wiki.el} and @file{planner.el}. The +development of Org-mode was fully independent, and both systems are +really different beasts in their basic ideas and implementation details. +However, I have later looked at John's code and learned from his +implementation of (i) links where the link itself is hidden and only a +description is shown, and (ii) popping up a calendar to select a date. @item Carsten Wimmer suggested some changes and helped fix a bug in linking to GNUS. diff --git a/orgcard.pdf b/orgcard.pdf Binary files differindex 531759968..82d95603d 100644 --- a/orgcard.pdf +++ b/orgcard.pdf diff --git a/orgcard.tex b/orgcard.tex index ed0c94dc5..0a7644293 100644 --- a/orgcard.tex +++ b/orgcard.tex @@ -1,5 +1,5 @@ % Reference Card for Org Mode -\def\orgversionnumber{4.19a} +\def\orgversionnumber{4.19b} \def\year{2006} % %**start of header @@ -401,22 +401,22 @@ To set archive location for current file, add a line like$^3$: {\bf External Links} -\key{\kbd{<file:/home/dominik/img/mars.jpg>}}{\rm file, absolute} -\key{\kbd{<file:papers/last.pdf>}}{\rm file, relative} -\key{\kbd{<file:projects.org::*that text>}}{\rm find headline} -\key{\kbd{<file:projects.org::find me>}}{\rm find tgt/string} -\key{\kbd{<file:projects.org::/regexp/>}}{\rm regexp search} -\key{\kbd{<http://www.astro.uva.nl/~dominik>}}{\rm on the web} -\key{\kbd{<mailto:adent@galaxy.net>}}{\rm EMail address} -\key{\kbd{<news:comp.emacs>}}{\rm Usenet group} -\key{\kbd{<bbdb:Richard Stallman>}}{\rm BBDB person} -\key{\kbd{<shell:ls *.org>}}{\rm shell command} -\key{\kbd{<gnus:group>}}{\rm GNUS group} -\key{\kbd{<gnus:group\#id>}}{\rm GNUS message} -\key{\kbd{<vm|wl|mhe|rmail:folder>}}{\rm Mail folder} -\key{\kbd{<vm|wl|mhe|rmail:folder\#id>}}{\rm Mail message} -\metax{\kbd{[[<external link>][description]]}}{\rm optional link text} -%\key{\kbd{<vm://myself@some.where.org/folder\#id>}}{\rm VM remote} +\key{\kbd{file:/home/dominik/img/mars.jpg}}{\rm file, absolute} +\key{\kbd{file:papers/last.pdf}}{\rm file, relative} +\key{\kbd{file:projects.org::*that text}}{\rm find headline} +\key{\kbd{file:projects.org::find me}}{\rm find tgt/string} +\key{\kbd{file:projects.org::/regexp/}}{\rm regexp search} +\key{\kbd{http://www.astro.uva.nl/~dominik}}{\rm on the web} +\key{\kbd{mailto:adent@galaxy.net}}{\rm EMail address} +\key{\kbd{news:comp.emacs}}{\rm Usenet group} +\key{\kbd{bbdb:Richard Stallman}}{\rm BBDB person} +\key{\kbd{shell:ls *.org}}{\rm shell command} +\key{\kbd{gnus:group}}{\rm GNUS group} +\key{\kbd{gnus:group\#id}}{\rm GNUS message} +\key{\kbd{vm|wl|mhe|rmail:folder}}{\rm Mail folder} +\key{\kbd{vm|wl|mhe|rmail:folder\#id}}{\rm Mail message} +\metax{\kbd{[[external link][description]]}}{\rm optional link text} +%\key{\kbd{vm://myself@some.where.org/folder\#id}}{\rm VM remote} \section{Tables} @@ -484,9 +484,9 @@ in lines starting with: {\tt | \# |}. \key{sum numbers in current column/rectangle}{C-c +} \key{copy down with increment}{S-RET$^4$} -A formula can also be typed directly into into a field and will -executed by \kbd{TAB}, \kbd{RET} and \kbd{C-c C-c}. A leading \kbd{=} -introduces a column formula, \kbd{:=} a named-field formula. +Formulas typed in field are executed by \kbd{TAB}, +\kbd{RET} and \kbd{C-c C-c}. \kbd{=} introduces a column +formula, \kbd{:=} a named-field formula. \key{Example: Add Col1 and Col2}{=\$1+\$2} \key{... with printf format specification}{=\$1+\$2;\%.2f} @@ -497,6 +497,7 @@ introduces a column formula, \kbd{:=} a named-field formula. {\bf Miscellaneous} \key{edit the current field in a separate window}{C-c `} +\key{make current field fully visible}{C-u TAB} \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} |