diff options
| author | Carsten Dominik <dominik@nb-dominik2.science.uva.nl> | 2008-01-31 11:32:08 +0100 |
|---|---|---|
| committer | Carsten Dominik <dominik@nb-dominik2.science.uva.nl> | 2008-01-31 11:32:08 +0100 |
| commit | 8fd900c6842d6f8d216ae6989b34c8de4a874e79 (patch) | |
| tree | 59a412ffd3ca8c5e2f6cacb5605f0b6fd683f36f | |
| parent | 2ff8fc1133b28c23d983d8eb6a2440a8b707c750 (diff) | |
| download | org-mode-8fd900c6842d6f8d216ae6989b34c8de4a874e79.tar.gz | |
Release 4.40release_4.40
| -rw-r--r-- | README | 11 | ||||
| -rw-r--r-- | org | 1353 | ||||
| -rw-r--r-- | org-publish.el | 154 | ||||
| -rw-r--r-- | org.el | 1925 | ||||
| -rw-r--r-- | org.pdf | bin | 539670 -> 559272 bytes | |||
| -rw-r--r-- | org.texi | 904 | ||||
| -rw-r--r-- | orgcard.pdf | bin | 57895 -> 57605 bytes | |||
| -rw-r--r-- | orgcard.tex | 178 | ||||
| -rw-r--r-- | xemacs/README | 9 | ||||
| -rw-r--r-- | xemacs/noutline.el | 1051 | ||||
| -rw-r--r-- | xemacs/ps-print-invisible.el | 225 |
11 files changed, 4304 insertions, 1506 deletions
@@ -1,4 +1,11 @@ -The is a distribution of org-mode +The is a distribution of Org-mode, a plain text notes and project planning +tool for Emacs. -The homepage of org-mode is at http://www.astro.uva.nl/~domnik/Tools/org/ +The homepage of Org-mode is at http://www.astro.uva.nl/~domnik/Tools/org/ +The manual is in the file org.pdf, it includes a section about installation. + +The xemacs directory contains special code for XEmacs users, in particular +a port of the GNU Emacs outline.el to XEmacs. Org-mode does not work +under XEmacs without this file installed. It did until version 4.37, +but no longer. @@ -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.37). + This manual is for Org-mode (version 4.40). 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.37). +This manual is for Org-mode (version 4.40). Copyright (C) 2004, 2005, 2006 Free Software Foundation @@ -53,9 +53,12 @@ This manual is for Org-mode (version 4.37). * Timestamps:: Assign date and time to items * Tags:: Tagging headlines and matching sets of tags * Agenda views:: Collecting information into views +* Embedded LaTeX:: LaTeX fragments and formulas * Exporting:: Sharing and publishing of notes * Publishing:: Create a web site of linked Org-mode files * Miscellaneous:: All the rest which did not fit elsewhere +* Extensions and Hacking:: It is possible to write add-on code +* History and Acknowledgments:: How Org-mode came into being * Index:: The fast road to specific information * Key Index:: Key bindings and where they are described @@ -64,7 +67,7 @@ This manual is for Org-mode (version 4.37). Introduction * Summary:: Brief summary of what Org-mode does -* Installation and activation:: How to install Org-mode +* Installation:: How to install Org-mode * Feedback:: Bug reports, ideas, patches etc. Document Structure @@ -78,6 +81,11 @@ Document Structure * Sparse trees:: Matches embedded in context * Plain lists:: Editing hand-formatted lists +Archiving + +* ARCHIVE tag:: Marking a tree as inactive +* Moving subtrees:: Moving a tree to an archive file + Tables * Built-in table editor:: Simple tables @@ -131,7 +139,7 @@ Timestamps Progress Logging -* Closing items:: When was this entry makred DONE? +* Closing items:: When was this entry marked DONE? * Clocking work time:: When exactly did you work on this item? Tags @@ -157,6 +165,14 @@ The weekly/daily agenda * Calendar/Diary integration:: Integrating Anniversaries and more * Sorting of agenda items:: The order of things +Embedded LaTeX + +* Math symbols:: TeX macros for symbols and Greek letters +* Subscripts and Superscripts:: Simple syntax for raising/lowering text +* LaTeX fragments:: Complex formulas made easy +* Processing LaTeX fragments:: Previewing LaTeX processing +* CDLaTeX mode:: Speed up entering of formulas + Exporting * ASCII export:: Exporting to plain ASCII @@ -180,7 +196,7 @@ Publishing Configuration * Project alist:: The central configuration variable -* File sources and destinations:: From here to there +* Sources and destinations:: From here to there * Selecting files:: What files are part of the project? * Publishing action:: Setting the function doing the publishing * Publishing options:: Tweaking HTML export @@ -196,21 +212,23 @@ Miscellaneous * Completion:: M-TAB knows what you need * Customization:: Adapting Org-mode to your taste -* Summary of in-buffer settings:: Using special lines to set options +* In-buffer settings:: Overview of the #+KEYWORDS * The very busy C-c C-c key:: When in doubt, press C-c C-c * Clean view:: Getting rid of leading stars in the outline * TTY keys:: Using Org-mode on a tty -* FAQ:: Frequently asked questions * Interaction:: Other Emacs packages * Bugs:: Things which do not work perfectly -* Acknowledgments:: These people provided feedback and more Interaction with other packages -* Extensions:: Third-party extensions for Org-mode * Cooperation:: Packages Org-mode cooperates with * Conflicts:: Packages that lead to conflicts +Extensions, Hooks and Hacking + +* Extensions:: Existing 3rd-part extensions +* Dynamic blocks:: Automatically filled blocks + File: org, Node: Introduction, Next: Document structure, Prev: Top, Up: Top @@ -220,11 +238,11 @@ File: org, Node: Introduction, Next: Document structure, Prev: Top, Up: Top * Menu: * Summary:: Brief summary of what Org-mode does -* Installation and activation:: How to install Org-mode +* Installation:: How to install Org-mode * Feedback:: Bug reports, ideas, patches etc. -File: org, Node: Summary, Next: Installation and activation, Prev: Introduction, Up: Introduction +File: org, Node: Summary, Next: Installation, Prev: Introduction, Up: Introduction 1.1 Summary =========== @@ -265,12 +283,12 @@ example: activating the minor Orgtbl-mode. There is a website for Org-mode which provides links to the newest -version of Org-mode, as well as additional information, screen shots -and example files. This page is located at +version of Org-mode, as well as additional information, frequently asked +questions (FAQ), links to tutorials etc. This page is located at `http://www.astro.uva.nl/~dominik/Tools/org/'. -File: org, Node: Installation and activation, Next: Feedback, Prev: Summary, Up: Introduction +File: org, Node: Installation, Next: Feedback, Prev: Summary, Up: Introduction 1.2 Installation and Activation =============================== @@ -299,6 +317,10 @@ them together with `org-install.el' on your load path. Then add to ;; This line only if org-mode is not part of the X/Emacs distribution. (require 'org-install) + If you use Org-mode with XEmacs, you also need to install the file +`noutline.el' from the `xemacs' subdirectory of the Org-mode +distribution. + With this setup, all files with extension `.org' will be put into Org-mode. As an alternative, make the first line of a file look like this: @@ -309,7 +331,7 @@ 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'. -File: org, Node: Feedback, Prev: Installation and activation, Up: Introduction +File: org, Node: Feedback, Prev: Installation, Up: Introduction 1.3 Feedback ============ @@ -534,18 +556,80 @@ File: org, Node: Archiving, Next: Sparse trees, Prev: Structure editing, Up: ============= When a project represented by a (sub)tree is finished, you may want to -move the tree to an archive place, either in the same file under a -special top-level heading, or even to a different file. +move the tree out of the way and to stop it from contributing to the +agenda. Org-mode knows two ways of archiving. You can mark a tree with +the ARCHIVE tag, or you can move an entire (sub)tree to a different +location. + +* Menu: + +* ARCHIVE tag:: Marking a tree as inactive +* Moving subtrees:: Moving a tree to an archive file + + +File: org, Node: ARCHIVE tag, Next: Moving subtrees, Prev: Archiving, Up: Archiving + +2.6.1 The ARCHIVE tag +--------------------- + +A headline that is marked with the ARCHIVE tag (*note Tags::) stays at +its location in the outline tree, but behaves in the following way: + - It does not open when you attempt to do so with a visibility + cycling command (*note Visibility cycling::). You can still open + it with a normal outline command like `show-all'. Or you can + modify the option `org-cycle-open-archived-trees'. + + - During sparse tree construction (*note Sparse trees::), matches in + archived subtrees are not exposed, unless you configure the option + `org-sparse-tree-open-archived-trees'. + + - During agenda view construction (*note Agenda views::), the + content of archived trees is ignored unless you configure the + option `org-agenda-skip-archived-trees'. + + - Archived trees are not exported (*note Exporting::), only the + headline is. Configure the details using the variable + `org-export-with-archived-trees'. + + The following commands allow to set or clear the ARCHIVE tag: + +`C-c C-x C-a' + Toggle the ARCHIVE tag for the current headline. When the tag is + set, the headline changes to a shadowish face, and the subtree + below it is hidden. + +`C-u C-c C-x C-a' + Check if any direct children of the current headline should be + archived. To do this, each subtree is checked for open TODO + entries. If none are found, the command offers to set the ARCHIVE + tag for the child. If the cursor is _not_ on a headline when this + command is invoked, the level 1 trees will be checked. + + +File: org, Node: Moving subtrees, Prev: ARCHIVE tag, Up: Archiving + +2.6.2 Moving subtrees +--------------------- + +Once an entire project is finished, you may want to move it to a +different location, either in the current file, or even in a different +file, the archive file. + `C-c $' Archive the subtree starting at the cursor position to the location - given by `org-archive-location'. + given by `org-archive-location'. + +`C-u C-c $' + Check if any direct children of the current headline could be + moved to the archive. To do this, each subtree is checked for + open TODO entries. If none are found, the command offers to move + it to the archive location. If the cursor is _not_ on a headline + when this command is invoked, the level 1 trees will be checked. - The default archive is a file in the same directory as the current -file, with the name derived by appending `_archive' to the current file -name. For information and examples on how to change this, see the -documentation string of the variable `org-archive-location'. If you -are also using the Org-mode agenda, archiving to a different file is a -good way to keep archived trees from contributing agenda items. + The default archive location is a file in the same directory as the +current file, with the name derived by appending `_archive' to the +current file name. For information and examples on how to change this, +see the documentation string of the variable `org-archive-location'. File: org, Node: Sparse trees, Next: Plain lists, Prev: Archiving, Up: Document structure @@ -1497,15 +1581,14 @@ insert it into an org-mode file, and to follow the link. not working correctly or accurately enough, you can write custom functions to select the search string and to do the search for particular file types - see *Note Custom searches::. The key - binding `C-c l' is only a suggestion - see *Note Installation and - activation::. + binding `C-c l' is only a suggestion - see *Note Installation::. `C-c C-l' Insert a link. This prompts for a link to be inserted into the buffer. You can just type a link, using text for an internal link, or one of the link type prefixes mentioned in the examples above. Through completion, all links stored during the current - session can be accessed. The link will be inserted into the + session can be accessed(1). The link will be inserted into the buffer, along with a descriptive text. Note that you don't have to use this command to insert a link. Links in Org-mode are plain text, and you can type or paste them straight into the buffer. By @@ -1539,10 +1622,10 @@ insert it into an org-mode file, and to follow the link. corresponding search. When the cursor is on a TAG list in a headline, it creates the corresponding TAGS view. If the cursor is on a 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 + Furthermore, it will visit text and remote files in `file:' links + with Emacs and select a suitable application for local non-text + files. Classification of files is based on file extension only. + See option `org-file-apps'. If you want to override the default application and visit the file with Emacs, use a `C-u' prefix. `mouse-2' @@ -1563,6 +1646,13 @@ insert it into an org-mode file, and to follow the link. command several times in direct succession moves through a ring of previously recorded positions. + ---------- Footnotes ---------- + + (1) After insertion of a stored link, the link will be removed from +the list of stored links. To keep it in the list later use, use a +triple `C-u' prefix to `C-c C-l', or configure the option +`org-keep-stored-link-after-insertion'. + File: org, Node: Search options, Next: Custom searches, Prev: Handling links, Up: Hyperlinks @@ -2009,7 +2099,7 @@ TIME STAMP WITH CLOSED KEYWORD TIME RANGE WITH CLOCK KEYWORD When using the clock to time the work that is being done on - specific items, time ranges preceeded by the CLOCK keyword are + specific items, time ranges preceded by the CLOCK keyword are inserted automatically into the file. The time stamps are enclosed in square brackets instead of angular brackets. *Note Clocking work time::. @@ -2135,7 +2225,7 @@ stop working on an aspect of a project. * Menu: -* Closing items:: When was this entry makred DONE? +* Closing items:: When was this entry marked DONE? * Clocking work time:: When exactly did you work on this item? @@ -2166,8 +2256,8 @@ File: org, Node: Clocking work time, Prev: Closing items, Up: Progress loggin Org-mode allows you to clock the time you spent on specific tasks in a project. When you start working on an item, you can start the clock. -When you stop working on that tast, or when you makr the task done, the -clock is stoppend and the corresponding time interval is recorded. It +When you stop working on that task, or when you mark the task done, the +clock is stopped and the corresponding time interval is recorded. It also computes the total time spent on each subtree of a project. `C-c C-x C-i' @@ -2193,7 +2283,18 @@ also computes the total time spent on each subtree of a project. This puts overlays at the end of each headline, showing the total time recorded under that heading, including the time of any subheadings. You can use visibility cycling to study the tree, but - the overlays disappear automatically when the buffer is changed. + the overlays disappear automatically when the buffer is changed. + +`C-c C-x C-r' + Insert a dynamic block containing a clock report as an org-mode + table into the current file. + #+BEGIN: clocktable :maxlevel 2 :emphasize nil + + #+END: clocktable + If such a block already exists, its content is replaced by the new + table. The `BEGIN' line can specify options: + :maxlevels Maximum level depth to which times are listed in the table. + :emphasize When `t', emphasize level one and level two items The `l' key may be used in the timeline (*note Timeline::) and in the agenda (*note Weekly/Daily agenda::) to show which tasks have been @@ -2354,7 +2455,7 @@ selects all lines tagged `:WORK:' or `:LAPTOP:'. The string `NIGHT'. -File: org, Node: Agenda views, Next: Exporting, Prev: Tags, Up: Top +File: org, Node: Agenda views, Next: Embedded LaTeX, Prev: Tags, Up: Top 8 Agenda Views ************** @@ -2434,12 +2535,11 @@ File: org, Node: Agenda dispatcher, Next: Weekly/Daily agenda, Prev: Agenda f ========================= The views are created through a dispatcher that should be bound to a -global key, for example `C-c a' (*note Installation and activation::). -In the following we will assume that `C-c a' is indeed how the -dispatcher is accessed and list keyboard access to commands -accordingly. After pressing `C-c a', an additional letter is required -to execute a command. The dispatcher offers the following default -commands: +global key, for example `C-c a' (*note Installation::). In the +following we will assume that `C-c a' is indeed how the dispatcher is +accessed and list keyboard access to commands accordingly. After +pressing `C-c a', an additional letter is required to execute a +command. The dispatcher offers the following default commands: `a' Create the calendar-like agenda (*note Weekly/Daily agenda::). @@ -2804,6 +2904,9 @@ Remote editing `:' Set tags for the current headline. +`a' + Toggle the ARCHIVE tag for the current headline. + `,' Set the priority for the current item. Org-mode prompts for the priority character. If you reply with <SPC>, the priority cookie @@ -2904,10 +3007,207 @@ Quit and Exit -File: org, Node: Exporting, Next: Publishing, Prev: Agenda views, Up: Top +File: org, Node: Embedded LaTeX, Next: Exporting, Prev: Agenda views, Up: Top -9 Exporting -*********** +9 Embedded LaTeX +**************** + +Plain ASCII is normally sufficient for almost all note taking. One +exception, however, are scientific notes which need to be able to +contain mathematical symbols and the occasional formula. LaTeX(1) is +widely used to typeset scientific documents. Org-mode supports +embedding LaTeX code into its files, because many academics are used to +read LaTeX source code, and because it can be readily processed into +images for HTML production. + + It is not necessary to mark LaTeX macros and code in any special way. +If you observe a few conventions, Org-mode knows how to find it and what +to do with it. + +* Menu: + +* Math symbols:: TeX macros for symbols and Greek letters +* Subscripts and Superscripts:: Simple syntax for raising/lowering text +* LaTeX fragments:: Complex formulas made easy +* Processing LaTeX fragments:: Previewing LaTeX processing +* CDLaTeX mode:: Speed up entering of formulas + + ---------- Footnotes ---------- + + (1) LaTeX is a macro system based on Donald E. Knuth's TeX system. +Many of the features described here as "LaTeX" are really from TeX, but +for simplicity I am blurring this distinction. + + +File: org, Node: Math symbols, Next: Subscripts and Superscripts, Prev: Embedded LaTeX, Up: Embedded LaTeX + +9.1 Math symbols +================ + +You can use LaTeX macros to insert special symbols like `\alpha' to +indicate the Greek letter, or `\to' to indicate an arrow. Completion +for these macros is available, just type `\' and maybe a few letters, +and press `M-<TAB>' to see possible completions. Unlike LaTeX code, +Org-mode allows these macros to be present without surrounding math +delimiters, for example: + + Angles are written as Greek letters \alpha, \beta and \gamma. + + During HTML export (*note HTML export::), these symbols are +translated into the proper syntax for HTML, for the above examples this +is `α' and `→', respectively. + + +File: org, Node: Subscripts and Superscripts, Next: LaTeX fragments, Prev: Math symbols, Up: Embedded LaTeX + +9.2 Subscripts and Superscripts +=============================== + +Just like in LaTeX, `^' and `_' are used to indicate super- and +subscripts. Again, these can be used without embedding them in +math-mode delimiters. To increase the readability of ASCII text, it is +not necessary (but OK) to surround multi-character sub- and superscripts +with curly braces. For example + + The mass if the sun is M_sun = 1.989 x 10^30 kg. The radius of + the sun is R_{sun} = 6.96 x 10^8 m. + + To avoid interpretation as raised or lowered text, you can quote `^' +and `_' with a backslash: `\_' and `\^'. + + During HTML export (*note HTML export::), subscript and superscripts +are surrounded with `<sub>' and `<sup>' tags, respectively. + + +File: org, Node: LaTeX fragments, Next: Processing LaTeX fragments, Prev: Subscripts and Superscripts, Up: Embedded LaTeX + +9.3 LaTeX fragments +=================== + +With symbols, sub- and superscripts, HTML is pretty much at its end when +it comes to representing mathematical formulas. More complex +expressions need a dedicated formula processor. To this end, Org-mode +can contain arbitrary LaTeX fragments. It provides commands to preview +the typeset result of these fragments, and upon export to HTML, all +fragments will be converted to images and inlined into the HTML +document. For this to work you need to be on a system with a working +LaTeX installation. You also need the `dvipng' program, available at +`http://sourceforge.net/projects/dvipng/'. + + LaTeX fragments don't need any special marking at all. The following +snippets will be identified as LaTeX source code: + * Environments of any kind. The only requirement is that the + `\begin' statement appears on a new line, preceded by only + whitespace. + + * Text within the usual LaTeX math delimiters. To avoid conflicts + with currency specifications, single `$' characters are only + recognized as math delimiters if the enclosed text contains at + most two line breaks, is directly attached to the `$' characters + with no whitespace in between, and if the closing `$' is followed + by whitespace or punctuation. For the other delimiters, there is + no such restriction, so when in doubt, use `\(...\)' as inline + math delimiters. + +For example: + + \begin{equation} % arbitrary environments, + x=\sqrt{b} % even tables, figures + \end{equation} % etc + + If $a^2=b$ and \( b=2 \), then the solution must be + either $$ a=+\sqrt{2} $$ or \[ a=-\sqrt{2} \]. + +If you need any of the delimiter ASCII sequences for other purposes, you +can configure the option `org-format-latex-options' to deselect the +ones you do not wish to have interpreted by the LaTeX converter. + + +File: org, Node: Processing LaTeX fragments, Next: CDLaTeX mode, Prev: LaTeX fragments, Up: Embedded LaTeX + +9.4 Processing LaTeX fragments +============================== + +LaTeX fragments can be processed to produce a preview images of the +typeset expressions: + +`C-c C-x C-l' + Produce a preview image of the LaTeX fragment at point and overlay + it over the source code. If there is no fragment at point, + process all fragments in the current entry (between two + headlines). When called with a prefix argument, process the + entire subtree. When called with two prefix arguments, or when + the cursor is before the first headline, process the entire buffer. + +`C-c C-c' + Remove the overlay preview images. + + During HTML export (*note HTML export::), all LaTeX fragments are +converted into images and inlined into the document if the following +setting is active: + + (setq org-export-with-LaTeX-fragments t) + + +File: org, Node: CDLaTeX mode, Prev: Processing LaTeX fragments, Up: Embedded LaTeX + +9.5 Using CDLaTeX to enter math +=============================== + +CDLaTeX-mode is a minor mode that is normally used in combination with a +major LaTeX mode like AUCTeX in order to speed-up insertion of +environments and math templates. Inside Org-mode, you can make use of +some of the features of cdlatex-mode. You need to install `cdlatex.el' +and `texmathp.el' (the latter comes also with AUCTeX) from +`http://www.astro.uva.nl/~dominik/Tools/cdlatex'. Don't turn +cdlatex-mode itself under Org-mode, but use the light version +`org-cdlatex-mode' that comes as part of Org-mode. Turn it on for the +current buffer with `M-x org-cdlatex-mode', or for all Org-mode files +with + + (add-hook 'org-mode-hook 'turn-on-org-cdlatex) + + When this mode is enabled, the following features are present (for +more details see the documentation of cdlatex-mode): + * Environment templates can be inserted with `C-c {'. + + * The <TAB> key will do template expansion if the cursor is inside a + LaTeX fragment(1). For example, <TAB> will expand `fr' to + `\frac{}{}' and position the cursor correctly inside the first + brace. Another <TAB> will get you into the second brace. Even + outside fragments, <TAB> will expand environment abbreviations at + the beginning of a line. For example, if you write `equ' at the + beginning of a line and press <TAB>, this abbreviation will be + expanded to an `equation' environment. To get a list of all + abbreviations, type `M-x cdlatex-command-help'. + + * Pressing `_' and `^' inside a LaTeX fragment will insert these + characters together with a pair of braces. If you use <TAB> to + move out of the braces, and if the braces surround only a single + character or macro, they are removed again (depending on the + variable `cdlatex-simplify-sub-super-scripts'). + + * Pressing the backquote ``' followed by a character inserts math + macros, also outside LaTeX fragments. If you wait more than 1.5 + seconds after the backquote, a help window will pop up. + + * Pressing the normal quote `'' followed by another character + modifies the symbol before point with an accent or a font. If you + wait more than 1.5 seconds after the backquote, a help window will + pop up. Character modification will work only inside LaTeX + fragments, outside the quote is normal. + + ---------- Footnotes ---------- + + (1) Org-mode has a method to test if the cursor is inside such a +fragment, see the documentation of the function +`org-inside-LaTeX-fragment-p'. + + +File: org, Node: Exporting, Next: Publishing, Prev: Embedded LaTeX, Up: Top + +10 Exporting +************ Org-mode documents can be exported into a variety of other formats. For printing and sharing of notes, ASCII export produces a readable and @@ -2933,8 +3233,8 @@ output produced. *Note Text interpretation::, for more details. File: org, Node: ASCII export, Next: HTML export, Prev: Exporting, Up: Exporting -9.1 ASCII export -================ +10.1 ASCII export +================= ASCII export produces a simple and very readable version of an Org-mode file. @@ -2959,16 +3259,16 @@ example, creates only top level headlines and does the rest as items. When headlines are converted to items, the indentation of the text following the headline is changed to fit nicely under the item. This is done with -the assumption that the first bodyline indicates the base indenation of -the body text. Any indenation larger than this is adjusted to preserve +the assumption that the first bodyline indicates the base indentation of +the body text. Any indentation larger than this is adjusted to preserve the layout relative to the first line. Should there be lines with less indentation than the first, these are left alone. File: org, Node: HTML export, Next: XOXO export, Prev: ASCII export, Up: Exporting -9.2 HTML export -=============== +10.2 HTML export +================ Org-mode contains an HTML (XHTML 1.0 strict) exporter with extensive HTML formatting, in ways similar to John Grubers _markdown_ language, @@ -3041,8 +3341,8 @@ section in the buffer. File: org, Node: XOXO export, Next: iCalendar export, Prev: HTML export, Up: Exporting -9.3 XOXO export -=============== +10.3 XOXO export +================ Org-mode contains an exporter that produces XOXO-style output. Currently, this exporter only handles the general outline structure and @@ -3057,8 +3357,8 @@ does not interpret any additional Org-mode features. File: org, Node: iCalendar export, Next: Text interpretation, Prev: XOXO export, Up: Exporting -9.4 iCalendar export -==================== +10.4 iCalendar export +===================== Some people like to use Org-mode for keeping track of projects, but still prefer a standard calendar application for anniversaries and @@ -3102,8 +3402,8 @@ this: File: org, Node: Text interpretation, Prev: iCalendar export, Up: Exporting -9.5 Text interpretation by the exporter -======================================= +10.5 Text interpretation by the exporter +======================================== The exporter backends interpret additional structure in the Org-mode file in order to produce better output. @@ -3117,8 +3417,8 @@ file in order to produce better output. File: org, Node: Comment lines, Next: Enhancing text, Prev: Text interpretation, Up: Text interpretation -9.5.1 Comment lines -------------------- +10.5.1 Comment lines +-------------------- Lines starting with `#' in column zero are treated as comments and will never be exported. Also entire subtrees starting with the word @@ -3131,8 +3431,8 @@ headline will not be exported either. File: org, Node: Enhancing text, Next: Export options, Prev: Comment lines, Up: Text interpretation -9.5.2 Enhancing text for export -------------------------------- +10.5.2 Enhancing text for export +-------------------------------- Some of the export backends of Org-mode allow for sophisticated text formatting, this is true in particular for the HTML backend. Org-mode @@ -3143,16 +3443,11 @@ formatted output. enumerator will be recognized and transformed if the backend supports lists. See *Note Plain lists::. - * You can make words *bold*, /italic/, and _underlined_ - - * Simple TeX-like math constructs are interpreted: + * You can make words *bold*, /italic/, _underlined_, `=code=', and + `+strikethrough+'. - - `10^22' and `J_n' are super- and subscripts. You can quote - `^' and `_' with a backslash: `\_' and `\^' - - - `\alpha' indicates a Greek letter, `\to' an arrow. You can - use completion for these macros, just type `\' and maybe a few - letters, and press `M-<TAB>' to see possible completions. + * Many TeX macros and entire LaTeX fragments are converted into HTML + entities or images (*note Embedded LaTeX::). * Tables are transformed into native tables under the exporter, if the export backend supports this. Data fields before the first @@ -3176,8 +3471,8 @@ which explains how to set export options with special lines in a buffer. File: org, Node: Export options, Prev: Enhancing text, Up: Text interpretation -9.5.3 Export options --------------------- +10.5.3 Export options +--------------------- The exporter recognizes special lines in the buffer which provide additional information. These lines may be put anywhere in the file. @@ -3195,7 +3490,7 @@ Completion::). #+LANGUAGE: language for HTML, e.g. `en' (`org-export-default-language') #+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 + #+OPTIONS: H:2 num:t toc:t \n:nil @:t ::t |:t ^:t *:nil TeX:t LaTeX:t The OPTIONS line is a compact form to specify export settings. Here you can: @@ -3208,12 +3503,13 @@ you can: |: turn on/off tables ^: turn on/off TeX-like syntax for sub- and superscripts. *: turn on/off emphasized text (bold, italic, underlined) - TeX: turn on/off TeX macros + TeX: turn on/off simple TeX macros in plain text + LaTeX: turn on/off LaTeX fragments File: org, Node: Publishing, Next: Miscellaneous, Prev: Exporting, Up: Top -10 Publishing +11 Publishing ************* Org-mode includes(1) a publishing management system that allows you to @@ -3241,7 +3537,7 @@ separately. Also make sure org.el is at least version 4.27. File: org, Node: Configuration, Next: Sample configuration, Prev: Publishing, Up: Publishing -10.1 Configuration +11.1 Configuration ================== Publishing needs significant configuration to specify files, destination @@ -3250,7 +3546,7 @@ and many other properties of a project. * Menu: * Project alist:: The central configuration variable -* File sources and destinations:: From here to there +* Sources and destinations:: From here to there * Selecting files:: What files are part of the project? * Publishing action:: Setting the function doing the publishing * Publishing options:: Tweaking HTML export @@ -3258,9 +3554,9 @@ and many other properties of a project. * Project page index:: Publishing a list of project files -File: org, Node: Project alist, Next: File sources and destinations, Prev: Configuration, Up: Configuration +File: org, Node: Project alist, Next: Sources and destinations, Prev: Configuration, Up: Configuration -10.1.1 The variable `org-publish-project-alist' +11.1.1 The variable `org-publish-project-alist' ----------------------------------------------- Org-publish is configured almost entirely through setting the value of @@ -3283,9 +3579,9 @@ which group together files requiring different publishing options. When you publish such a "meta-project" all the components will also publish. -File: org, Node: File sources and destinations, Next: Selecting files, Prev: Project alist, Up: Configuration +File: org, Node: Sources and destinations, Next: Selecting files, Prev: Project alist, Up: Configuration -10.1.2 Sources and destinations for files +11.1.2 Sources and destinations for files ----------------------------------------- Most properties are optional, but some should always be set. In @@ -3297,9 +3593,9 @@ and where to put published files. will be published. -File: org, Node: Selecting files, Next: Publishing action, Prev: File sources and destinations, Up: Configuration +File: org, Node: Selecting files, Next: Publishing action, Prev: Sources and destinations, Up: Configuration -10.1.3 Selecting files +11.1.3 Selecting files ---------------------- By default, all files with extension `.org' in the base directory are @@ -3316,7 +3612,7 @@ properties File: org, Node: Publishing action, Next: Publishing options, Prev: Selecting files, Up: Configuration -10.1.4 Publishing Action +11.1.4 Publishing Action ------------------------ Publishing means that a file is copied to the destination directory and @@ -3340,7 +3636,7 @@ provides one for attachments (files that only need to be copied): File: org, Node: Publishing options, Next: Publishing links, Prev: Publishing action, Up: Configuration -10.1.5 Options for the HTML exporter +11.1.5 Options for the HTML exporter ------------------------------------ The property list can be used to set many export options for the HTML @@ -3353,9 +3649,11 @@ respective variable for details. `:headline-levels' `org-export-headline-levels' `:section-numbers' `org-export-with-section-numbers' `:table-of-contents' `org-export-with-toc' +`:archived-trees' `org-export-with-archived-trees' `:emphasize' `org-export-with-emphasize' `:sub-superscript' `org-export-with-sub-superscripts' `:TeX-macros' `org-export-with-TeX-macros' +`:LaTeX-fragments' `org-export-with-LaTeX-fragments' `:fixed-width' `org-export-with-fixed-width' `:timestamps' `org-export-with-timestamps' . @@ -3384,7 +3682,7 @@ however, override everything. File: org, Node: Publishing links, Next: Project page index, Prev: Publishing options, Up: Configuration -10.1.6 Links between published files +11.1.6 Links between published files ------------------------------------ To create a link from one Org-mode file to another, you would use @@ -3399,10 +3697,24 @@ careful with relative pathnames, and provided you have also configured org-publish to upload the related files, these links will work too. *Note Complex example:: for an example of this usage. + Sometime an Org-mode file to be published may contain links that are +only valid in your production environment, but not in the publishing +location. In this case, use the property + +`:link-validation-function' Function to validate links + +to define a function for checking link validity. This function must +accept two arguments, the file name and a directory relative to which +the file name is interpreted in the production environment. If this +function returns `nil', then the HTML generator will only insert a +description into the HTML file, but no link. One option for this +function is `org-publish-validate-link' which checks if the given file +is part of any project in `org-publish-project-alist'. + File: org, Node: Project page index, Prev: Publishing links, Up: Configuration -10.1.7 Project page index +11.1.7 Project page index ------------------------- The following properties may be used to control publishing of an index @@ -3420,7 +3732,7 @@ of files or summary page for a given project. File: org, Node: Sample configuration, Next: Triggering publication, Prev: Configuration, Up: Publishing -10.2 Sample configuration +11.2 Sample configuration ========================= Below we provide two example configurations. The first one is a simple @@ -3435,7 +3747,7 @@ more complex, with a multi-component project. File: org, Node: Simple example, Next: Complex example, Prev: Sample configuration, Up: Sample configuration -10.2.1 Example: simple publishing configuration +11.2.1 Example: simple publishing configuration ----------------------------------------------- This example publishes a set of Org-mode files to the `public_html' @@ -3454,7 +3766,7 @@ directory on the local machine. File: org, Node: Complex example, Prev: Simple example, Up: Sample configuration -10.2.2 Example: complex publishing configuration +11.2.2 Example: complex publishing configuration ------------------------------------------------ This more complicated example publishes an entire website, including @@ -3502,7 +3814,7 @@ right place on the webserver, and publishing images to it. File: org, Node: Triggering publication, Prev: Sample configuration, Up: Publishing -10.3 Triggering publication +11.3 Triggering publication =========================== Once org-publish is properly configured, you can publish with the @@ -3525,28 +3837,26 @@ functions normally only publish changed files. You can override this and force publishing of all files by giving a prefix argument. -File: org, Node: Miscellaneous, Next: Index, Prev: Publishing, Up: Top +File: org, Node: Miscellaneous, Next: Extensions and Hacking, Prev: Publishing, Up: Top -11 Miscellaneous +12 Miscellaneous **************** * Menu: * Completion:: M-TAB knows what you need * Customization:: Adapting Org-mode to your taste -* Summary of in-buffer settings:: Using special lines to set options +* In-buffer settings:: Overview of the #+KEYWORDS * The very busy C-c C-c key:: When in doubt, press C-c C-c * Clean view:: Getting rid of leading stars in the outline * TTY keys:: Using Org-mode on a tty -* FAQ:: Frequently asked questions * Interaction:: Other Emacs packages * Bugs:: Things which do not work perfectly -* Acknowledgments:: These people provided feedback and more File: org, Node: Completion, Next: Customization, Prev: Miscellaneous, Up: Miscellaneous -11.1 Completion +12.1 Completion =============== Org-mode supports in-buffer completion. This type of completion does @@ -3572,9 +3882,9 @@ buffer and use the key to complete text right there. * Elsewhere, complete dictionary words using ispell. -File: org, Node: Customization, Next: Summary of in-buffer settings, Prev: Completion, Up: Miscellaneous +File: org, Node: Customization, Next: In-buffer settings, Prev: Completion, Up: Miscellaneous -11.2 Customization +12.2 Customization ================== There are more than 100 variables that can be used to customize @@ -3583,12 +3893,12 @@ describing the variables here. A structured overview of customization variables is available with `M-x org-customize'. Or select `Browse Org Group' from the `Org->Customization' menu. Many settings can also be activated on a per-file basis, by putting special lines into the buffer -(*note Summary of in-buffer settings::). +(*note In-buffer settings::). -File: org, Node: Summary of in-buffer settings, Next: The very busy C-c C-c key, Prev: Customization, Up: Miscellaneous +File: org, Node: In-buffer settings, Next: The very busy C-c C-c key, Prev: Customization, Up: Miscellaneous -11.3 Summary of in-buffer settings +12.3 Summary of in-buffer settings ================================== Org-mode uses special lines in the buffer to define settings on a @@ -3654,9 +3964,9 @@ file is visited again in a new Emacs session. details see *Note Export options::. -File: org, Node: The very busy C-c C-c key, Next: Clean view, Prev: Summary of in-buffer settings, Up: Miscellaneous +File: org, Node: The very busy C-c C-c key, Next: Clean view, Prev: In-buffer settings, Up: Miscellaneous -11.4 The very busy C-c C-c key +12.4 The very busy C-c C-c key ============================== The key `C-c C-c' has many purposes in org-mode, which are all @@ -3666,6 +3976,9 @@ circumstances it means something like _Hey Org-mode, look here and update according to what you see here_. Here is a summary of what this means in different contexts. + - If there are highlights in the buffer from the creation of a sparse + tree, or from clock display, remove these highlights. + - If the cursor is in one of the special `#+KEYWORD' lines, this triggers scanning the buffer for these lines and updating the information. @@ -3695,7 +4008,7 @@ means in different contexts. File: org, Node: Clean view, Next: TTY keys, Prev: The very busy C-c C-c key, Up: Miscellaneous -11.5 A cleaner outline view +12.5 A cleaner outline view =========================== Some people find it noisy and distracting that the Org-mode headlines @@ -3775,9 +4088,9 @@ RET' in that file. The reverse operation is `M-x org-convert-to-oddeven-levels'. -File: org, Node: TTY keys, Next: FAQ, Prev: Clean view, Up: Miscellaneous +File: org, Node: TTY keys, Next: Interaction, Prev: Clean view, Up: Miscellaneous -11.6 Using org-mode on a tty +12.6 Using org-mode on a tty ============================ Org-mode uses a number of keys that are not accessible on a tty. This @@ -3817,178 +4130,9 @@ Default Alternative 1 Alternative 2 <down>' -File: org, Node: FAQ, Next: Interaction, Prev: TTY keys, Up: Miscellaneous - -11.7 Frequently asked questions -=============================== - - 1. When I try to use Org-mode, I always get `(wrong-type-argument - keymapp nil)'. - This is a conflict with an outdated version of the `allout.el'. - See *Note Conflicts::. - - 2. Org-mode seems to be a useful default mode for the various - `README' files I have scattered through my directories. How do I - turn it on for all `README' files? - - (add-to-list 'auto-mode-alist '("README$" . org-mode)) - - 3. I would like to use editing features of org-mode in other modes, - is this possible? - Not really. For tables there is `orgtbl-mode' which implements the - table editor as a minor mode. For other features you need to - switch to Org-mode temporarily, or prepare text in a different - buffer. - - 4. Can I get the visibility-cycling features in outline-mode and - outline-minor-mode? - Yes, these functions are written in a way that they are - independent of the outline setup. The following setup provides - standard Org-mode functionality in outline-mode on <TAB> and - `S-<TAB>'. For outline-minor-mode, we use `C-<TAB>' instead of - <TAB>, because <TAB> usually has mode-specific tasks. - (add-hook 'outline-minor-mode-hook - (lambda () - (define-key outline-minor-mode-map [(control tab)] 'org-cycle) - (define-key outline-minor-mode-map [(shift tab)] 'org-global-cycle))) - (add-hook 'outline-mode-hook - (lambda () - (define-key outline-mode-map [(tab)] 'org-cycle) - (define-key outline-mode-map [(shift tab)] 'org-global-cycle))) - - Or check out `outline-magic.el', which does this and also provides - promotion and demotion functionality. `outline-magic.el' is - available at `http://www.astro.uva.nl/~dominik/Tools/OutlineMagic'. - - 5. Some of my links stopped working after I upgraded to a version - 4.20 or later. Why is this, and how can I fix it? - These must be links in plain text, containing white space, such as - `bbdb:Richard Stallman'. You need to protect these links by - putting double brackets around them, like `[[bbdb:Richard - Stallman]]'. - - 6. I see that Org-mode now creates links using the double bracket - convention that hides the link part and the brackets, only showing - the description part. How can I convert my old links to this new - format? - Execute once in each Org-mode file: `M-x org-upgrade-old-links'. - This replaces angular brackets with the new link format. - - 7. I don't care if you find the new bracket links great, I am - attached to the old style using angular brackets and no hiding of - the link text. Please give them back to me, don't tell me it is - not possible! - Would I let you down like that? If you must, you can do this - - (setq org-link-style 'plain - org-link-format "<%s>") - - 8. When I am executing shell/elisp links I always get a confirmation - prompt and need to type `yes <RET>', that's 4 key presses! Can I - get rid of this? - The confirmation is there to protect you from unwantingly execute - potentially dangerous commands. For example, imagine a link - `[[shell:rm -rf ~/*][Google Search]]'. In an Org-mode buffer, this - command would look like `Google Search', but really it would remove - your home directory. If you wish, you can make it easier to - respond to the query by setting `org-confirm-shell-link-function' - and/or `org-confirm-elisp-link-function' to `y-or-n-p'. Then a - single `y' keypress will be enough to confirm those links. It is - also possible to turn off this check entirely, but I do not - recommend to do this. Be warned. - - 9. 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::. - - 10. 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. - - 11. 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 - to be exported as item lists are level 4 at least, even if that - does mean there is a level jump. For example: - - * Todays top priorities - **** TODO write a letter to xyz - **** TODO Finish the paper - **** Pick up kids at the school - - Alternatively, if you need a specific value for the heading/item - transition in a particular file, use the `+OPTIONS' line to - configure the `H' switch. - - +OPTIONS: H:2; ... - - 12. 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. - - 13. 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 Conflicts::. - - 14. One of my table columns has started to fill up with `#ERROR'. - What is going on? - Org-mode tried to compute the column from other fields using a - formula stored in the `#+TBLFM:' line just below the table, and - the evaluation of the formula fails. Fix the fields used in the - formula, or fix the formula, or remove it! - - 15. 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'. - - 16. 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>. - - 17. 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 - before deciding to do this. Integrating Org-mode information into - the diary is, however, possible. You need to turn on _fancy diary - display_ by setting in `.emacs': - - (add-hook 'diary-display-hook 'fancy-diary-display) - - Then include the following line into your `~/diary' file, in order - to get the entries from all files listed in the variable - `org-agenda-files': - - &%%(org-diary) - You may also select specific files with - - &%%(org-diary) ~/path/to/some/org-file.org - &%%(org-diary) ~/path/to/another/org-file.org - - If you now launch the calendar and press `d' to display a diary, - the headlines of entries containing a timestamp, date range, - schedule, or deadline referring to the selected date will be - listed. Just like Org-mode's agenda view, the diary for _today_ - contains additional entries for overdue deadlines and scheduled - items. See also the documentation of the `org-diary' function. - Under XEmacs, it is not possible to jump back from the diary to - the org, this works only in the agenda buffer. - - - -File: org, Node: Interaction, Next: Bugs, Prev: FAQ, Up: Miscellaneous +File: org, Node: Interaction, Next: Bugs, Prev: TTY keys, Up: Miscellaneous -11.8 Interaction with other packages +12.7 Interaction with other packages ==================================== Org-mode lives in the world of GNU Emacs and interacts in various ways @@ -3996,40 +4140,13 @@ with other code out there. * Menu: -* Extensions:: Third-party extensions for Org-mode * Cooperation:: Packages Org-mode cooperates with * Conflicts:: Packages that lead to conflicts -File: org, Node: Extensions, Next: Cooperation, Prev: Interaction, Up: Interaction - -11.8.1 Third-party extensions for Org-mode ------------------------------------------- - -The following extensions for Org-mode have been written by other people: - -`org-mouse.el' by Piotr Zielinski - This package implements extended mouse functionality for Org-mode. - It allows you to cycle visibility and to edit the document - structure with the mouse. Best of all, it provides a - context-sensitive menu on <mouse-3> that changes depending on the - context of a mouse-click. `org-mouse.el' is freely available at - `http://www.cl.cam.ac.uk/~pz215/files/org-mouse.el'. - -`org-publish.el' by David O'Toole - This package provides facilities for publishing related sets of - Org-mode files together with linked files like images as a - webpages. It is highly configurable and can be used for other - publishing purposes as well. As of Org-mode version 4.30, - `org-publish.el' is part of the Org-mode distribution. It is not - yet part of Emacs, however, due to a pending copyright assignment. - In the mean time, `org-publish.el' can be downloaded from David's - site: `http://dto.freeshell.org/e/org-publish.el'. - - -File: org, Node: Cooperation, Next: Conflicts, Prev: Extensions, Up: Interaction +File: org, Node: Cooperation, Next: Conflicts, Prev: Interaction, Up: Interaction -11.8.2 Packages that Org-mode cooperates with +12.7.1 Packages that Org-mode cooperates with --------------------------------------------- `calc.el' by Dave Gillespie @@ -4054,6 +4171,11 @@ File: org, Node: Cooperation, Next: Conflicts, Prev: Extensions, Up: Interac setup. See the installation instructions in the file `constants.el'. +`cdlatex.el' by Carsten Dominik + Org-mode can make use of the cdlatex package to efficiently enter + LaTeX fragments into Org-mode files. `cdlatex.el' is not part of + Emacs, find it on the web. + `remember.el' by John Wiegley Org mode cooperates with remember, see *Note Remember::. `Remember.el' is not part of Emacs, find it on the web. @@ -4065,7 +4187,7 @@ File: org, Node: Cooperation, Next: Conflicts, Prev: Extensions, Up: Interac File: org, Node: Conflicts, Prev: Cooperation, Up: Interaction -11.8.3 Packages that lead to conflicts with Org-mode +12.7.2 Packages that lead to conflicts with Org-mode ---------------------------------------------------- `allout.el' by Ken Manheimer @@ -4099,9 +4221,9 @@ File: org, Node: Conflicts, Prev: Cooperation, Up: Interaction in the paragraph above about CUA mode also applies here. -File: org, Node: Bugs, Next: Acknowledgments, Prev: Interaction, Up: Miscellaneous +File: org, Node: Bugs, Prev: Interaction, Up: Miscellaneous -11.9 Bugs +12.8 Bugs ========= Here is a list of things that should work differently, but which I have @@ -4126,10 +4248,6 @@ found too hard to fix. open the file), it does so silently. No error message is displayed. - * Plain list items should be able to hold a TODO item. - Unfortunately this has so many technical problems that I will only - consider this change for the next major release (5.0). - * The remote-editing commands in the agenda buffer cannot be undone with `undo' called from within the agenda buffer. But you can go to the corresponding buffer (using <TAB> or <RET> and execute @@ -4139,22 +4257,138 @@ found too hard to fix. If a formula uses _calculated_ fields further down the row, multiple recalculation may be needed to get all fields consistent. - * Several words in a row may *be made bold*, but this does not work - if the string is distributed over two lines. + * A single letter cannot be made bold, for example `*a*'. * The exporters work well, but could be made more efficient. -File: org, Node: Acknowledgments, Prev: Bugs, Up: Miscellaneous +File: org, Node: Extensions and Hacking, Next: History and Acknowledgments, Prev: Miscellaneous, Up: Top -11.10 Acknowledgments -===================== +Appendix A Extensions, Hooks and Hacking +**************************************** + +This appendix lists extensions for Org-mode written by other authors. +It also covers some aspects where users can easily extend the +functionality of Org-mode. + +* Menu: + +* Extensions:: Existing 3rd-part extensions +* Dynamic blocks:: Automatically filled blocks + + +File: org, Node: Extensions, Next: Dynamic blocks, Prev: Extensions and Hacking, Up: Extensions and Hacking + +A.1 Third-party extensions for Org-mode +======================================= + +The following extensions for Org-mode have been written by other people: + +`org-mouse.el' by Piotr Zielinski + This package implements extended mouse functionality for Org-mode. + It allows you to cycle visibility and to edit the document + structure with the mouse. Best of all, it provides a + context-sensitive menu on <mouse-3> that changes depending on the + context of a mouse-click. `org-mouse.el' is freely available at + `http://www.cl.cam.ac.uk/~pz215/files/org-mouse.el'. + +`org-publish.el' by David O'Toole + This package provides facilities for publishing related sets of + Org-mode files together with linked files like images as a + webpages. It is highly configurable and can be used for other + publishing purposes as well. As of Org-mode version 4.30, + `org-publish.el' is part of the Org-mode distribution. It is not + yet part of Emacs, however, a delay caused by the preparations for + the 22.1 release. In the mean time, `org-publish.el' can be + downloaded from David's site: + `http://dto.freeshell.org/e/org-publish.el'. + +`org-blog.el' by David O'Toole + A blogging plug-in for `org-publish.el'. + `http://dto.freeshell.org/notebook/OrgMode.html'. + +`org-blogging.el' by Bastien Guerry + Publish Org-mode files as blogs. + `http://www.cognition.ens.fr/~guerry/org-blogging.html'. + + +File: org, Node: Dynamic blocks, Prev: Extensions, Up: Extensions and Hacking + +A.2 Dynamic blocks +================== + +Org-mode documents can contain _dynamic blocks_. These are specially +marked regions that are updates by some user-written function. A good +example for such a block is the clock table inserted by the command +`C-c C-x C-r' (*note Clocking work time::). + + Dynamic block are enclosed by a BEGIN-END structure that assigns a +name to the block and can also specify parameters for the function +producing the content of the block. + + #+BEGIN: myblock :parameter1 value1 :parameter2 value2 ..... + + #+END: + + Dynamic blocks are updated with the following commands + +`C-c C-x C-u' + Update dynamic block at point. -Org-mode was created by Carsten Dominik, who still maintains it at the -Org-mode homepage `http://www.astro.uva.nl/~dominik/Tools/org/'. The -following people (in alphabetic order) have helped the development -along with ideas, suggestions and patches. Many thanks to all of you, -Org-mode would not be what it is without your input. +`C-u C-c C-x C-u' + Update all dynamic blocks in the current file. + + Updating a dynamic block means to remove all the text between BEGIN +and END, parse the BEGIN line for parameters and then call the specific +writer function for this block to insert the new content. For a block +with name `myblock', the writer function is `org-dblock-write:myblock' +with as only parameter a property list with the parameters given in the +begin line. Here is a trivial example of a block that keeps track of +when the block update function was last run: + + #+BEGIN: block-update-time :format "on %m/%d/%Y at %H:%M" + + #+END: + +The corresponding block writer function could look like this: + + (defun org-dblock-write:date-and-time (params) + (let ((fmt (or (plist-get params :format) "%d. %m. %Y"))) + (insert "Last block update at: " + (format-time-string fmt (current-time))))) + + If you want to make sure that all dynamic blocks are always +up-to-date, you could add the function `org-update-all-dblocks' to a +hook, for example `before-save-hook'. `org-update-all-dblocks' is +written in a way that is does nothing in buffers that are not in +Org-mode. + + +File: org, Node: History and Acknowledgments, Next: Index, Prev: Extensions and Hacking, Up: Top + +Appendix B History and Acknowledgments +************************************** + +The beginnings of Org-mode go back to 2003. It was borne out of +frustration over the user interface of the emacs outline-mode. All I +wanted was to make working with an outline tree possible without having +to remember more than 10 commands just for hiding and unhiding parts of +the outline tree, and to allow to restructure a tree easily. Visibility +cycling and structure editing were originally implemented in the package +`outline-magic.el', but quickly moved to the more general `org.el'. +TODO entries, basic time stamps, and table support were added next, and +highlight the two main goals that Org-mode still has today: To create +a new, outline-based, plain text mode with innovative and intuitive +editing features, and to incorporate project planning functionality +directly into a notes file. + + Since the first release, hundreds of emails to me or on +`emacs-orgmode@gnu.org' have provided a constant stream of bug reports, +feedback, new ideas, and sometimes even patches and add-on code. Many +thanks to everyone who has helped to improve this package. I am trying +to keep here a list of the people who had significant influence in +shaping one or more aspects of Org-mode. The list may not be complete, +if I have forgotten someone, please accept my apologies and let me know. * Thomas Baumann contributed the code for links to the MH-E email system. @@ -4167,8 +4401,9 @@ Org-mode would not be what it is without your input. * Pavel Chalmoviansky influenced the agenda treatment of items with specified time. - * Gregory Chenov patched support for lisp forms into table - calculations and improved XEmacs compatibility. + * Gregory Chernov patched support for lisp forms into table + calculations and improved XEmacs compatibility, in particular by + porting `nouline.el' to XEmacs. * Sacha Chua suggested to copy some linking code from Planner. @@ -4180,9 +4415,15 @@ Org-mode would not be what it is without your input. * Nic Ferrier contributed mailcap and XOXO support. + * Niels Giessen had the idea to automatically archive DONE trees. + + * Bastien Guerry provoded extensive feedback. + * Kai Grossjohann pointed out key-binding conflicts caused by Org-mode. + * Leon Liu asked for embedded LaTeX and tested it. + * Stefan Monnier provided a patch to keep the Emacs-Lisp compiler happy. @@ -4217,6 +4458,9 @@ Org-mode would not be what it is without your input. * Linking to VM/BBDB/GNUS was inspired by Tom Shannon's `organizer-mode.el'. + * Daniel Sinder came up with the idea of internal archiving by + locking subtrees. + * David O'Toole wrote `org-publish.el' and drafted the manual chapter about publishing. @@ -4246,15 +4490,17 @@ Org-mode would not be what it is without your input. links with mouse-1. -File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top +File: org, Node: Index, Next: Key Index, Prev: History and Acknowledgments, Up: Top -12 Index -******** +Index +***** * Menu: -* acknowledgments: Acknowledgments. (line 6) +* acknowledgments: History and Acknowledgments. + (line 6) +* action, for publishing: Publishing action. (line 6) * active region <1>: HTML export. (line 10) * active region <2>: ASCII export. (line 9) * active region <3>: Built-in table editor. @@ -4263,19 +4509,17 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * agenda: Weekly/Daily agenda. (line 6) * agenda commands, custom: Agenda dispatcher. (line 6) * agenda dispatcher: Agenda dispatcher. (line 6) -* agenda files, removing buffers: Agenda commands. (line 205) +* agenda files, removing buffers: Agenda commands. (line 208) * agenda views: Agenda views. (line 6) * agenda, for single file: Timeline. (line 6) * allout.el: Conflicts. (line 6) -* allout.el, conflict with: FAQ. (line 8) * angular brackets, around links: External links. (line 38) * applescript, for calendar update: iCalendar export. (line 38) -* archive locations: Archiving. (line 13) +* archive locations: Moving subtrees. (line 21) * archiving: Archiving. (line 6) * ASCII export: ASCII export. (line 6) * author: Feedback. (line 6) -* autoload: Installation and activation. - (line 6) +* autoload: Installation. (line 6) * BBDB links: External links. (line 6) * bold text: Enhancing text. (line 15) * bug reports: Feedback. (line 6) @@ -4292,6 +4536,7 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * CamelCase links: Internal links. (line 6) * CamelCase links, completion of: CamelCase links. (line 6) * category: Categories. (line 6) +* cdlatex.el: Cooperation. (line 29) * checkboxes: Plain lists. (line 36) * children, subtree visibility state: Visibility cycling. (line 10) * clean outline view: Clean view. (line 6) @@ -4303,15 +4548,14 @@ 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: Handling links. (line 44) -* completion, of links: Handling links. (line 28) +* completion, of file names: Handling links. (line 43) +* completion, of links: Handling links. (line 27) * completion, of option keywords <1>: Completion. (line 6) * completion, of option keywords: Export options. (line 6) * Completion, of option keywords: Per file keywords. (line 17) * completion, of tags <1>: Completion. (line 6) * completion, of tags: Setting tags. (line 11) -* completion, of TeX symbols <1>: Completion. (line 6) -* completion, of TeX symbols: Enhancing text. (line 19) +* completion, of TeX symbols: Completion. (line 6) * completion, of TODO keywords <1>: Completion. (line 6) * completion, of TODO keywords: Workflow states. (line 12) * constants, in calculations: Formula syntax. (line 26) @@ -4326,16 +4570,17 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * cutting, of subtrees: Structure editing. (line 6) * cycling, of TODO states: TODO basics. (line 13) * cycling, visibility: Visibility cycling. (line 6) -* dangerous commands: FAQ. (line 70) * date stamps: Time stamps. (line 6) * date, reading in minibuffer: Creating timestamps. (line 71) * DEADLINE keyword: Time stamps. (line 43) * deadlines: Time stamps. (line 6) * demotion, of subtrees: Structure editing. (line 6) -* diary entries, creating from agenda: Agenda commands. (line 173) +* diary entries, creating from agenda: Agenda commands. (line 176) * diary integration: Calendar/Diary integration. (line 6) * dictionary word completion: Completion. (line 6) +* directories, for publishing: Sources and destinations. + (line 6) * dispatching agenda commands: Agenda dispatcher. (line 6) * document structure: Document structure. (line 6) * DONE, final TODO keyword: Per file keywords. (line 20) @@ -4347,23 +4592,23 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * enhancing text: Enhancing text. (line 6) * evaluate time range: Creating timestamps. (line 66) * exporting: Exporting. (line 6) -* exporting a subtree: FAQ. (line 112) * exporting, not: Comment lines. (line 6) * extended TODO keywords: TODO extensions. (line 6) +* external archiving: Moving subtrees. (line 6) * external links: External links. (line 6) * external links, in HTML export: HTML export. (line 35) -* FAQ: FAQ. (line 6) +* FAQ: Summary. (line 41) * feedback: Feedback. (line 6) * file links: External links. (line 6) * file links, searching: Search options. (line 6) -* file name completion: Handling links. (line 44) +* file name completion: Handling links. (line 43) * files, adding to agenda list: Agenda files. (line 12) -* filing subtrees: Archiving. (line 6) -* fixed width: Enhancing text. (line 30) +* files, selecting for publishing: Selecting files. (line 6) +* fixed width: Enhancing text. (line 25) * fixed-width sections: Export options. (line 25) * folded, subtree visibility state: Visibility cycling. (line 10) * folding, sparse trees: Sparse trees. (line 6) -* following links: Handling links. (line 59) +* following links: Handling links. (line 58) * format specifier: Formula syntax. (line 34) * format, of links: Link format. (line 6) * formula editing: Editing/debugging formulas. @@ -4375,8 +4620,7 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * formula, in tables: Built-in table editor. (line 135) * global cycling: Visibility cycling. (line 22) -* global keybindings: Installation and activation. - (line 6) +* global keybindings: Installation. (line 6) * global TODO list: Global TODO list. (line 6) * global visibility states: Visibility cycling. (line 22) * GNUS links: External links. (line 6) @@ -4390,43 +4634,44 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * headlines: Headlines. (line 6) * hide text: Visibility cycling. (line 6) * hiding leading stars: Clean view. (line 6) +* history: History and Acknowledgments. + (line 6) * HTML export: HTML export. (line 6) * hyperlinks: Hyperlinks. (line 6) * iCalendar export: iCalendar export. (line 6) -* in-buffer settings: Summary of in-buffer settings. - (line 6) -* indentation, of tables: FAQ. (line 136) -* indirect buffers: FAQ. (line 88) +* in-buffer settings: In-buffer settings. (line 6) +* index, of published pages: Project page index. (line 6) * Info links: External links. (line 6) * inheritance, of tags: Tag inheritance. (line 6) -* inserting links: Handling links. (line 28) -* installation: Installation and activation. - (line 6) +* inserting links: Handling links. (line 27) +* installation: Installation. (line 6) +* internal archiving: ARCHIVE tag. (line 6) * internal links: Internal links. (line 6) * internal links, in HTML export: HTML export. (line 35) * introduction: Introduction. (line 6) * italic text: Enhancing text. (line 15) * jumping, to headlines: Motion. (line 6) -* keybindings, global: Installation and activation. - (line 6) -* keymapp nil error: FAQ. (line 6) +* keybindings, global: Installation. (line 6) * keyword options: Per file keywords. (line 6) +* LaTeX fragments: Export options. (line 25) +* LaTeX fragments, export: Enhancing text. (line 18) +* LaTeX interpretation: Embedded LaTeX. (line 6) * linebreak preservation: Export options. (line 25) -* linebreak, forced: Enhancing text. (line 37) -* link completion: Handling links. (line 28) +* linebreak, forced: Enhancing text. (line 32) +* link completion: Handling links. (line 27) * link format: Link format. (line 6) * links, external: External links. (line 6) * links, in HTML export: HTML export. (line 35) * links, internal: Internal links. (line 6) -* links, returning to: Handling links. (line 85) +* links, publishing: Publishing links. (line 6) +* links, returning to: Handling links. (line 84) * Lisp forms, as table formulas: Lisp formulas. (line 6) * lists, hand-formatted: Enhancing text. (line 11) * 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 88) -* mark ring: Handling links. (line 81) +* mark ring: Handling links. (line 80) * marking characters, tables: Advanced features. (line 34) * matching, of tags: Matching headline tags. (line 6) @@ -4444,11 +4689,14 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * option keyword completion: Completion. (line 6) * options, for customization: Customization. (line 6) * options, for export: Export options. (line 6) +* options, for publishing: Publishing options. (line 6) * ordered lists: Plain lists. (line 6) * org-agenda, command: Weekly/Daily agenda. (line 9) -* org-mode, turning on: Installation and activation. - (line 30) +* org-blog.el: Extensions. (line 25) +* org-blogging.el: Extensions. (line 29) +* org-mode, turning on: Installation. (line 34) * org-mouse.el: Extensions. (line 8) +* org-publish-project-alist: Project alist. (line 6) * org-publish.el: Extensions. (line 14) * orgtbl-mode: orgtbl-mode. (line 6) * outline tree: Headlines. (line 6) @@ -4465,7 +4713,9 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * priorities, of agenda items: Sorting of agenda items. (line 6) * progress logging: Progress logging. (line 6) +* projects, for publishing: Project alist. (line 6) * promotion, of subtrees: Structure editing. (line 6) +* publishing: Publishing. (line 6) * quoted HTML tags: Export options. (line 25) * ranges, time: Time stamps. (line 6) * recomputing table fields: Column formulas. (line 27) @@ -4474,7 +4724,7 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * region, active <3>: Built-in table editor. (line 165) * region, active: Structure editing. (line 51) -* remember.el <1>: Cooperation. (line 29) +* remember.el <1>: Cooperation. (line 34) * remember.el: Remember. (line 6) * richer text: Enhancing text. (line 6) * RMAIL links: External links. (line 6) @@ -4484,7 +4734,6 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * section-numbers: Export options. (line 25) * setting tags: Setting tags. (line 6) * SHELL links: External links. (line 6) -* shell links, confirmation: FAQ. (line 70) * show all, command: Visibility cycling. (line 31) * show all, global visibility state: Visibility cycling. (line 22) * show hidden text: Visibility cycling. (line 6) @@ -4495,8 +4744,7 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * sparse tree, for TODO: TODO basics. (line 26) * sparse tree, tag based: Tags. (line 6) * sparse trees: Sparse trees. (line 6) -* special keywords: Summary of in-buffer settings. - (line 6) +* special keywords: In-buffer settings. (line 6) * spreadsheet capabilities: Table calculations. (line 6) * storing links: Handling links. (line 9) * structure editing: Structure editing. (line 6) @@ -4512,22 +4760,24 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top (line 6) * table editor, table.el: table.el. (line 6) * table of contents: Export options. (line 25) -* table.el <1>: Cooperation. (line 30) +* table.el <1>: Cooperation. (line 35) * table.el: table.el. (line 6) * tables <1>: Export options. (line 25) * tables: Tables. (line 6) -* tables, export: Enhancing text. (line 26) +* tables, export: Enhancing text. (line 21) * tag completion: Completion. (line 6) * tag searches: Tag searches. (line 6) * tags: Tags. (line 6) * tags view: Matching headline tags. (line 6) * templates, for remember: Remember. (line 23) -* TeX interpretation: Enhancing text. (line 17) +* TeX interpretation: Embedded LaTeX. (line 6) * TeX macros: Export options. (line 25) +* TeX macros, export: Enhancing text. (line 18) * TeX symbol completion: Completion. (line 6) * TeX-like syntax for sub- and superscripts: Export options. (line 25) -* thanks: Acknowledgments. (line 6) +* thanks: History and Acknowledgments. + (line 6) * time stamps: Time stamps. (line 6) * time, reading in minibuffer: Creating timestamps. (line 71) * time-sorted view: Timeline. (line 6) @@ -4565,15 +4815,16 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top File: org, Node: Key Index, Prev: Index, Up: Top -13 Key Index -************ +3 Key Index +*********** * Menu: -* +: Agenda commands. (line 120) -* ,: Agenda commands. (line 112) -* -: Agenda commands. (line 126) +* ': CDLaTeX mode. (line 43) +* +: Agenda commands. (line 123) +* ,: Agenda commands. (line 115) +* -: Agenda commands. (line 129) * .: Agenda commands. (line 91) * :: Agenda commands. (line 109) * <: Creating timestamps. (line 78) @@ -4584,22 +4835,27 @@ File: org, Node: Key Index, Prev: Index, Up: Top (line 64) * <right>: Agenda commands. (line 83) * <SPC>: Agenda commands. (line 28) -* <TAB> <1>: Agenda commands. (line 35) -* <TAB> <2>: Built-in table editor. +* <TAB> <1>: CDLaTeX mode. (line 23) +* <TAB> <2>: Agenda commands. (line 35) +* <TAB> <3>: Built-in table editor. (line 57) -* <TAB> <3>: Plain lists. (line 48) +* <TAB> <4>: Plain lists. (line 48) * <TAB>: Visibility cycling. (line 10) -* > <1>: Agenda commands. (line 148) +* > <1>: Agenda commands. (line 151) * >: Creating timestamps. (line 79) -* C: Agenda commands. (line 188) -* c: Agenda commands. (line 166) +* ^: CDLaTeX mode. (line 33) +* _: CDLaTeX mode. (line 33) +* `: CDLaTeX mode. (line 39) +* a: Agenda commands. (line 112) +* C: Agenda commands. (line 191) +* c: Agenda commands. (line 169) * C-#: Built-in table editor. (line 155) * C-,: Agenda files. (line 18) * C-c !: Creating timestamps. (line 21) -* C-c $: Archiving. (line 9) -* C-c %: Handling links. (line 81) -* C-c &: Handling links. (line 85) +* C-c $: Moving subtrees. (line 10) +* C-c %: Handling links. (line 80) +* C-c &: Handling links. (line 84) * C-c ' <1>: Editing/debugging formulas. (line 20) * C-c ': Built-in table editor. @@ -4613,7 +4869,7 @@ File: org, Node: Key Index, Prev: Index, Up: Top (line 92) * C-c .: Creating timestamps. (line 10) * C-c /: Sparse trees. (line 15) -* C-c :: Enhancing text. (line 34) +* C-c :: Enhancing text. (line 29) * C-c ;: Comment lines. (line 11) * C-c <: Creating timestamps. (line 25) * C-c <TAB>: Built-in table editor. @@ -4633,7 +4889,7 @@ File: org, Node: Key Index, Prev: Index, Up: Top * C-c `: Built-in table editor. (line 181) * C-c a a: Weekly/Daily agenda. (line 9) -* C-c a C: Agenda dispatcher. (line 30) +* C-c a C: Agenda dispatcher. (line 29) * C-c a M: Matching headline tags. (line 15) * C-c a m: Matching headline tags. @@ -4647,28 +4903,30 @@ File: org, Node: Key Index, Prev: Index, Up: Top * C-c C-b: Motion. (line 15) * C-c C-c <1>: The very busy C-c C-c key. (line 6) -* C-c C-c <2>: Setting tags. (line 10) -* C-c C-c <3>: table.el. (line 6) -* C-c C-c <4>: Editing/debugging formulas. +* C-c C-c <2>: Processing LaTeX fragments. + (line 15) +* C-c C-c <3>: Setting tags. (line 10) +* C-c C-c <4>: table.el. (line 6) +* C-c C-c <5>: Editing/debugging formulas. (line 16) -* C-c C-c <5>: Built-in table editor. +* C-c C-c <6>: Built-in table editor. (line 54) * C-c C-c: Plain lists. (line 85) -* C-c C-d <1>: Agenda commands. (line 133) +* C-c C-d <1>: Agenda commands. (line 136) * C-c C-d: Creating timestamps. (line 37) * C-c C-f: Motion. (line 12) * C-c C-j: Motion. (line 21) -* C-c C-l: Handling links. (line 28) +* C-c C-l: Handling links. (line 27) * C-c C-n: Motion. (line 8) * C-c C-o <1>: Creating timestamps. (line 33) -* C-c C-o: Handling links. (line 59) +* C-c C-o: Handling links. (line 58) * 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 119) * C-c C-r: Timeline. (line 13) -* C-c C-s <1>: Agenda commands. (line 130) +* C-c C-s <1>: Agenda commands. (line 133) * C-c C-s: Creating timestamps. (line 48) * C-c C-t <1>: Clocking work time. (line 20) * C-c C-t: TODO basics. (line 13) @@ -4678,12 +4936,17 @@ File: org, Node: Key Index, Prev: Index, Up: Top * C-c C-x a: ASCII export. (line 9) * C-c C-x b: HTML export. (line 11) * C-c C-x c: iCalendar export. (line 20) -* C-c C-x C-c: Agenda commands. (line 195) +* C-c C-x C-a: ARCHIVE tag. (line 27) +* C-c C-x C-c: Agenda commands. (line 198) * C-c C-x C-d: Clocking work time. (line 28) * C-c C-x C-i <1>: iCalendar export. (line 15) * C-c C-x C-i: Clocking work time. (line 12) * C-c C-x C-k: Structure editing. (line 36) +* C-c C-x C-l: Processing LaTeX fragments. + (line 9) * C-c C-x C-o: Clocking work time. (line 14) +* C-c C-x C-r: Clocking work time. (line 35) +* C-c C-x C-u: Dynamic blocks. (line 21) * C-c C-x C-w <1>: Built-in table editor. (line 108) * C-c C-x C-w: Structure editing. (line 36) @@ -4705,23 +4968,27 @@ File: org, Node: Key Index, Prev: Index, Up: Top * C-c C-x v h: HTML export. (line 14) * C-c C-y: Creating timestamps. (line 66) * C-c l: Handling links. (line 9) +* C-c {: CDLaTeX mode. (line 21) * C-c |: Built-in table editor. (line 40) * C-c ~: table.el. (line 18) +* C-u C-c $: Moving subtrees. (line 12) * C-u C-c .: Creating timestamps. (line 16) * C-u C-c =: Built-in table editor. (line 139) -* C-u C-c C-l: Handling links. (line 44) +* C-u C-c C-l: Handling links. (line 43) +* C-u C-c C-x C-a: ARCHIVE tag. (line 30) +* C-u C-c C-x C-u: Dynamic blocks. (line 22) * D: Agenda commands. (line 68) * d: Agenda commands. (line 65) * f: Agenda commands. (line 44) * g: Agenda commands. (line 72) -* H: Agenda commands. (line 192) -* i: Agenda commands. (line 173) -* I: Agenda commands. (line 153) +* H: Agenda commands. (line 195) +* i: Agenda commands. (line 176) +* I: Agenda commands. (line 156) * l: Agenda commands. (line 51) * L: Agenda commands. (line 32) -* M: Agenda commands. (line 179) +* M: Agenda commands. (line 182) * M-<down>: Built-in table editor. (line 82) * M-<left> <1>: Built-in table editor. @@ -4759,167 +5026,179 @@ File: org, Node: Key Index, Prev: Index, Up: Top * M-S-<up>: Structure editing. (line 30) * mouse-1 <1>: Agenda commands. (line 35) * mouse-1 <2>: Creating timestamps. (line 82) -* mouse-1: Handling links. (line 73) +* mouse-1: Handling links. (line 72) * mouse-2 <1>: Agenda commands. (line 35) -* mouse-2: Handling links. (line 73) +* mouse-2: Handling links. (line 72) * mouse-3 <1>: Agenda commands. (line 28) -* mouse-3: Handling links. (line 78) +* mouse-3: Handling links. (line 77) * n: Agenda commands. (line 19) -* O: Agenda commands. (line 155) +* O: Agenda commands. (line 158) * o: Agenda commands. (line 59) -* P: Agenda commands. (line 117) +* P: Agenda commands. (line 120) * p: Agenda commands. (line 20) -* q: Agenda commands. (line 202) +* q: Agenda commands. (line 205) * r <1>: Agenda commands. (line 76) * r: Global TODO list. (line 20) -* S: Agenda commands. (line 183) -* S-<down> <1>: Agenda commands. (line 126) +* S: Agenda commands. (line 186) +* S-<down> <1>: Agenda commands. (line 129) * S-<down> <2>: Creating timestamps. (line 58) * S-<down> <3>: Priorities. (line 25) * S-<down>: Plain lists. (line 66) -* S-<left> <1>: Agenda commands. (line 144) +* S-<left> <1>: Agenda commands. (line 147) * S-<left> <2>: Creating timestamps. (line 53) * S-<left>: TODO basics. (line 20) * S-<RET>: Built-in table editor. (line 170) -* S-<right> <1>: Agenda commands. (line 136) +* S-<right> <1>: Agenda commands. (line 139) * S-<right> <2>: Creating timestamps. (line 53) * S-<right>: TODO basics. (line 20) * S-<TAB> <1>: Built-in table editor. (line 61) * S-<TAB>: Visibility cycling. (line 22) -* S-<up> <1>: Agenda commands. (line 120) +* S-<up> <1>: Agenda commands. (line 123) * S-<up> <2>: Creating timestamps. (line 58) * S-<up> <3>: Priorities. (line 25) * S-<up>: Plain lists. (line 66) * T: Agenda commands. (line 104) * t: Agenda commands. (line 100) * w: Agenda commands. (line 62) -* x: Agenda commands. (line 205) -* X: Agenda commands. (line 158) +* x: Agenda commands. (line 208) +* X: Agenda commands. (line 161) Tag Table: Node: Top959 -Node: Introduction8845 -Node: Summary9159 -Node: Installation and activation11415 -Node: Feedback13073 -Node: Document structure13859 -Node: Outlines14625 -Node: Headlines15285 -Node: Visibility cycling15908 -Ref: Visibility cycling-Footnote-117383 -Ref: Visibility cycling-Footnote-217441 -Node: Motion17491 -Node: Structure editing18275 -Node: Archiving20384 -Node: Sparse trees21244 -Ref: Sparse trees-Footnote-123223 -Ref: Sparse trees-Footnote-223315 -Node: Plain lists23430 -Ref: Plain lists-Footnote-127328 -Node: Tables27685 -Node: Built-in table editor28233 -Node: Narrow columns35840 -Ref: Narrow columns-Footnote-137779 -Node: Table calculations37825 -Node: Formula syntax39145 -Ref: Formula syntax-Footnote-142050 -Node: Lisp formulas42350 -Node: Column formulas43139 -Node: Advanced features44901 -Node: Named-field formulas48155 -Node: Editing/debugging formulas48795 -Node: Appetizer50553 -Node: orgtbl-mode51656 -Node: table.el52147 -Node: Hyperlinks53124 -Node: Link format53829 -Node: Internal links55122 -Ref: Internal links-Footnote-157111 -Node: Radio targets57243 -Node: CamelCase links57958 -Node: External links58456 -Node: Handling links60587 -Node: Search options65137 -Ref: Search options-Footnote-166911 -Node: Custom searches66992 -Node: Remember68040 -Node: TODO items71730 -Node: TODO basics72594 -Node: TODO extensions74121 -Node: Workflow states74916 -Node: TODO types75784 -Ref: TODO types-Footnote-177442 -Node: Per file keywords77524 -Ref: Per file keywords-Footnote-178978 -Node: Priorities79206 -Node: Timestamps80422 -Node: Time stamps80812 -Node: Creating timestamps83910 -Node: Progress logging87256 -Node: Closing items87786 -Node: Clocking work time88581 -Node: Tags90266 -Node: Tag inheritance91028 -Node: Setting tags91965 -Ref: Setting tags-Footnote-195095 -Ref: Setting tags-Footnote-295207 -Node: Tag searches95287 -Node: Agenda views96496 -Node: Agenda files98035 -Ref: Agenda files-Footnote-198995 -Ref: Agenda files-Footnote-299144 -Node: Agenda dispatcher99336 -Node: Weekly/Daily agenda101466 -Node: Categories102601 -Node: Time-of-day specifications103249 -Node: Calendar/Diary integration105225 -Node: Sorting of agenda items106602 -Node: Global TODO list107434 -Node: Matching headline tags108795 -Node: Timeline109738 -Node: Agenda commands110611 -Node: Exporting116330 -Node: ASCII export117463 -Node: HTML export118749 -Node: XOXO export121583 -Node: iCalendar export122022 -Node: Text interpretation123845 -Node: Comment lines124322 -Node: Enhancing text124791 -Node: Export options126715 -Node: Publishing128317 -Ref: Publishing-Footnote-1129113 -Node: Configuration129309 -Node: Project alist130030 -Node: File sources and destinations131101 -Node: Selecting files131653 -Node: Publishing action132406 -Node: Publishing options133521 -Node: Publishing links135560 -Node: Project page index136363 -Node: Sample configuration137141 -Node: Simple example137633 -Node: Complex example138306 -Node: Triggering publication140382 -Node: Miscellaneous141038 -Node: Completion141797 -Node: Customization142793 -Node: Summary of in-buffer settings143400 -Node: The very busy C-c C-c key146642 -Node: Clean view148157 -Node: TTY keys150734 -Node: FAQ152335 -Node: Interaction160133 -Node: Extensions160593 -Node: Cooperation161845 -Node: Conflicts163539 -Node: Bugs165131 -Node: Acknowledgments167029 -Node: Index170467 -Node: Key Index192859 +Node: Introduction9455 +Node: Summary9768 +Node: Installation12035 +Node: Feedback13824 +Node: Document structure14595 +Node: Outlines15361 +Node: Headlines16021 +Node: Visibility cycling16644 +Ref: Visibility cycling-Footnote-118119 +Ref: Visibility cycling-Footnote-218177 +Node: Motion18227 +Node: Structure editing19011 +Node: Archiving21120 +Node: ARCHIVE tag21678 +Node: Moving subtrees23353 +Node: Sparse trees24394 +Ref: Sparse trees-Footnote-126373 +Ref: Sparse trees-Footnote-226465 +Node: Plain lists26580 +Ref: Plain lists-Footnote-130478 +Node: Tables30835 +Node: Built-in table editor31383 +Node: Narrow columns38990 +Ref: Narrow columns-Footnote-140929 +Node: Table calculations40975 +Node: Formula syntax42295 +Ref: Formula syntax-Footnote-145200 +Node: Lisp formulas45500 +Node: Column formulas46289 +Node: Advanced features48051 +Node: Named-field formulas51305 +Node: Editing/debugging formulas51945 +Node: Appetizer53703 +Node: orgtbl-mode54806 +Node: table.el55297 +Node: Hyperlinks56274 +Node: Link format56979 +Node: Internal links58272 +Ref: Internal links-Footnote-160261 +Node: Radio targets60393 +Node: CamelCase links61108 +Node: External links61606 +Node: Handling links63737 +Ref: Handling links-Footnote-168323 +Node: Search options68560 +Ref: Search options-Footnote-170334 +Node: Custom searches70415 +Node: Remember71463 +Node: TODO items75153 +Node: TODO basics76017 +Node: TODO extensions77544 +Node: Workflow states78339 +Node: TODO types79207 +Ref: TODO types-Footnote-180865 +Node: Per file keywords80947 +Ref: Per file keywords-Footnote-182401 +Node: Priorities82629 +Node: Timestamps83845 +Node: Time stamps84235 +Node: Creating timestamps87332 +Node: Progress logging90678 +Node: Closing items91208 +Node: Clocking work time92003 +Node: Tags94172 +Node: Tag inheritance94934 +Node: Setting tags95871 +Ref: Setting tags-Footnote-199001 +Ref: Setting tags-Footnote-299113 +Node: Tag searches99193 +Node: Agenda views100402 +Node: Agenda files101946 +Ref: Agenda files-Footnote-1102906 +Ref: Agenda files-Footnote-2103055 +Node: Agenda dispatcher103247 +Node: Weekly/Daily agenda105363 +Node: Categories106498 +Node: Time-of-day specifications107146 +Node: Calendar/Diary integration109122 +Node: Sorting of agenda items110499 +Node: Global TODO list111331 +Node: Matching headline tags112692 +Node: Timeline113635 +Node: Agenda commands114508 +Node: Embedded LaTeX120286 +Ref: Embedded LaTeX-Footnote-1121378 +Node: Math symbols121568 +Node: Subscripts and Superscripts122333 +Node: LaTeX fragments123177 +Node: Processing LaTeX fragments125246 +Node: CDLaTeX mode126192 +Ref: CDLaTeX mode-Footnote-1128676 +Node: Exporting128824 +Node: ASCII export129961 +Node: HTML export131251 +Node: XOXO export134087 +Node: iCalendar export134528 +Node: Text interpretation136353 +Node: Comment lines136832 +Node: Enhancing text137303 +Node: Export options138995 +Node: Publishing140662 +Ref: Publishing-Footnote-1141458 +Node: Configuration141654 +Node: Project alist142372 +Node: Sources and destinations143438 +Node: Selecting files143985 +Node: Publishing action144733 +Node: Publishing options145848 +Node: Publishing links148000 +Node: Project page index149513 +Node: Sample configuration150291 +Node: Simple example150783 +Node: Complex example151456 +Node: Triggering publication153532 +Node: Miscellaneous154188 +Node: Completion154822 +Node: Customization155818 +Node: In-buffer settings156403 +Node: The very busy C-c C-c key159634 +Node: Clean view161271 +Node: TTY keys163848 +Node: Interaction165457 +Node: Cooperation165854 +Node: Conflicts167756 +Node: Bugs169348 +Node: Extensions and Hacking170971 +Node: Extensions171457 +Node: Dynamic blocks173027 +Node: History and Acknowledgments174945 +Node: Index179726 +Node: Key Index202566 End Tag Table diff --git a/org-publish.el b/org-publish.el index cabea06..ad0ace3 100644 --- a/org-publish.el +++ b/org-publish.el @@ -1,12 +1,12 @@ ;;; org-publish.el --- publish related org-mode files as a website -;; Copyright (C) 2006 David O'Toole +;; Copyright (C) 2006 Free Software Foundation, Inc. ;; Author: David O'Toole <dto@gnu.org> ;; Keywords: hypermedia, outlines -;; Version: +;; Version: -;; $Id: org-publish.el,v 1.67 2006/05/30 10:44:31 dto Exp dto $ +;; $Id: org-publish.el,v 1.73 2006/06/15 12:43:48 dto Exp $ ;; This file is free software; you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by @@ -23,8 +23,6 @@ ;; the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, ;; Boston, MA 02110-1301, USA. -;; This file is NOT part of GNU Emacs. - ;;; Commentary: ;; Requires at least version 4.27 of org.el @@ -39,7 +37,7 @@ ;; to allow configurable publishing of related sets of files as a ;; complete website. ;; -;; org-publish.el can do the following: +;; org-publish.el can do the following: ;; ;; + Publish all one's org-files to html ;; + Upload html, images, attachments and other files to a web server @@ -51,7 +49,7 @@ ;; Special thanks to the org-mode maintainer Carsten Dominik for his ;; ideas, enthusiasm, and cooperation. -;;; Installation: +;;; Installation: ;; Put org-publish.el in your load path, byte-compile it, and then add ;; the following lines to your emacs initialization file: @@ -65,13 +63,13 @@ ;; already in the file org-install.el, and hence don't need to be put ;; in your emacs initialization file in this case. -;;; Usage: +;;; Usage: ;; ;; The program's main configuration variable is ;; `org-publish-project-alist'. See below for example configurations ;; with commentary. -;; The main interactive functions are: +;; The main interactive functions are: ;; ;; M-x org-publish ;; M-x org-publish-all @@ -81,7 +79,7 @@ ;;;; Simple example configuration: ;; (setq org-publish-project-alist -;; (list +;; (list ;; '("org" . (:base-directory "~/org/" ;; :base-extension "org" ;; :publishing-directory "~/public_html" @@ -103,10 +101,10 @@ ;; following example configuration to your specific paths, run M-x ;; org-publish-all, and it should publish the files to the correct ;; directories on the web server, transforming the *.org files into -;; HTML, and leaving other files alone. +;; HTML, and leaving other files alone. ;; (setq org-publish-project-alist -;; (list +;; (list ;; '("orgfiles" :base-directory "~/org/" ;; :base-extension "org" ;; :publishing-directory "/ssh:user@host:~/html/notebook/" @@ -118,12 +116,12 @@ ;; :style "<link rel=stylesheet href=\"../other/mystyle.css\" type=\"text/css\">" ;; :auto-preamble t ;; :auto-postamble nil) -;; +;; ;; ("images" :base-directory "~/images/" ;; :base-extension "jpg\\|gif\\|png" ;; :publishing-directory "/ssh:user@host:~/html/images/" ;; :publishing-function org-publish-attachment) -;; +;; ;; ("other" :base-directory "~/other/" ;; :base-extension "css" ;; :publishing-directory "/ssh:user@host:~/html/other/" @@ -140,13 +138,13 @@ ;;; List of user-visible changes since version 1.27 -;; 1.65: Remove old "composite projects". They're redundant. +;; 1.65: Remove old "composite projects". They're redundant. ;; 1.64: Allow meta-projects with :components ;; 1.57: Timestamps flag is now called "org-publish-use-timestamps-flag" ;; 1.52: Properly set default for :index-filename ;; 1.48: Composite projects allowed. ;; :include keyword allowed. -;; 1.43: Index no longer includes itself in the index. +;; 1.43: Index no longer includes itself in the index. ;; 1.42: Fix "function definition is void" error ;; when :publishing-function not set in org-publish-current-file. ;; 1.41: Fixed bug where index isn't published on first try. @@ -158,7 +156,7 @@ ;;; Code: -(eval-when-compile +(eval-when-compile (require 'cl)) (defgroup org-publish nil @@ -167,16 +165,16 @@ :group 'org) -(defcustom org-publish-project-alist nil +(defcustom org-publish-project-alist nil "Association list to control publishing behavior. Each element of the alist is a publishing 'project.' The CAR of each element is a string, uniquely identifying the project. The -CDR of each element is in one of the following forms: +CDR of each element is in one of the following forms: (:property value :property value ... ) OR, - + (:components (\"project-1\" \"project-2\" ...)) When the CDR of an element of org-publish-project-alist is in @@ -191,7 +189,7 @@ setting overrides the value of the corresponding user variable override everything. Most properties are optional, but some should always be set: - + :base-directory Directory containing publishing source files :base-extension Extension (without the dot!) of source files. This can be a regular expression. @@ -207,7 +205,7 @@ value may be a list of filenames to include. The filenames are considered relative to the publishing directory. When both :include and :exclude properties are given values, the -exclusion step happens first. +exclusion step happens first. One special property controls which back-end function to use for publishing files in the project. This can be used to extend the @@ -249,29 +247,29 @@ learn more about their use and default values. The following properties may be used to control publishing of an index of files or summary page for a given project. - :auto-index Whether to publish an index during + :auto-index Whether to publish an index during org-publish-current-project or org-publish-all. :index-filename Filename for output of index. Defaults to 'index.org' (which becomes 'index.html') :index-title Title of index page. Defaults to name of file. :index-function Plugin function to use for generation of index. - Defaults to 'org-publish-org-index', which + Defaults to 'org-publish-org-index', which generates a plain list of links to all files - in the project. + in the project. " :group 'org-publish :type 'alist) (defcustom org-publish-use-timestamps-flag t - "When non-nil, use timestamp checking to publish only changed files. + "When non-nil, use timestamp checking to publish only changed files. When nil, do no timestamp checking and always publish all files." :group 'org-publish :type 'boolean) -(defcustom org-publish-timestamp-directory "~/.org-timestamps/" +(defcustom org-publish-timestamp-directory "~/.org-timestamps/" "Name of directory in which to store publishing timestamps." :group 'org-publish :type 'string) @@ -287,8 +285,8 @@ files." (concat org-publish-timestamp-directory filename ".timestamp")) -(defun org-publish-needed-p (filename) - "Check whether file should be published. +(defun org-publish-needed-p (filename) + "Check whether file should be published. If org-publish-use-timestamps-flag is set to nil, this function always returns t. Otherwise, check the timestamps folder to determine whether file should be published." @@ -304,7 +302,7 @@ whether file should be published." ;; check timestamp. ok if timestamp file doesn't exist (let* ((timestamp (org-publish-timestamp-filename filename)) (rtn (file-newer-than-file-p filename timestamp))) - (if rtn + (if rtn ;; handle new timestamps (if (not (file-exists-p timestamp)) ;; create file @@ -321,11 +319,25 @@ whether file should be published." (set-file-times timestamp))) +;;;; A hash mapping files to project names + + +(defvar org-publish-files (make-hash-table :test 'equal) "Hash +table mapping file names to project names.") + + +;;;; Checking filenames against this hash + + +(defun org-publish-validate-link (link) + (gethash (file-truename link) org-publish-files)) + + ;;;; Getting project information out of org-publish-project-alist (defun org-publish-get-plists (&optional project-name) - "Return a list of property lists for project PROJECT-NAME. + "Return a list of property lists for project PROJECT-NAME. When argument is not given, return all property lists for all projects." (let ((alist (if project-name (list (assoc project-name org-publish-project-alist)) @@ -333,19 +345,25 @@ When argument is not given, return all property lists for all projects." (project nil) (plists nil) (components nil)) + + ;; + ;; (while (setq project (pop alist)) + ;; what kind of project is it? (if (setq components (plist-get (cdr project) :components)) ;; meta project. annotate each plist with name of enclosing project - (setq plists - (append plists - (mapcar (lambda (p) - (plist-put p :project-name (car project))) - (mapcan 'org-publish-get-plists components)))) + (setq plists + (append plists + (apply 'append + (mapcar 'org-publish-get-plists components)))) ;; normal project - (let ((p (cdr project))) - (setq p (plist-put p :project-name (car project))) - (setq plists (append plists (list (cdr project))))))) - ;; + (setq plists (append plists (list (cdr project))))) + ;; + (dolist (p plists) + (let* ((exclude (plist-get p :exclude)) + (files (org-publish-get-base-files p exclude))) + (dolist (f files) + (puthash (file-truename f) (car project) org-publish-files))))) plists)) @@ -371,8 +389,8 @@ matching filenames." ;; include extra files (let ((inc nil)) (while (setq inc (pop include-list)) - (setq allfiles (cons (concat dir inc) allfiles)))) - + (setq allfiles (cons (expand-file-name inc dir) allfiles)))) + allfiles)) @@ -380,14 +398,8 @@ matching filenames." "Figure out which project a given FILENAME belongs to, if any. Filename should contain full path. Returns name of project, or nil if not found." - (let ((found nil)) - (mapcar - (lambda (plist) - (let ((files (org-publish-get-base-files plist))) - (if (member (expand-file-name filename) files) - (setq found (plist-get plist :project-name))))) - (org-publish-get-plists)) - found)) + (org-publish-get-plists) + (gethash (file-truename filename) org-publish-files)) (defun org-publish-get-plist-from-filename (filename) @@ -396,18 +408,19 @@ nil if not found." (mapcar (lambda (plist) (let ((files (org-publish-get-base-files plist))) - (if (member (expand-file-name filename) files) - (setq found plist)))) + (if (member (expand-file-name filename) files) + (setq found plist)))) (org-publish-get-plists)) found)) + ;;;; Pluggable publishing back-end functions (defun org-publish-org-to-html (plist filename) - "Publish an org file to HTML. -PLIST is the property list for the given project. + "Publish an org file to HTML. +PLIST is the property list for the given project. FILENAME is the filename of the org file to be published." (require 'org) (let* ((arg (plist-get plist :headline-levels))) @@ -416,14 +429,14 @@ FILENAME is the filename of the org file to be published." (org-export-as-html arg nil plist) ;; get rid of HTML buffer (kill-buffer (current-buffer))))) - + (defun org-publish-attachment (plist filename) "Publish a file with no transformation of any kind. -PLIST is the property list for the given project. +PLIST is the property list for the given project. FILENAME is the filename of the file to be published." ;; make sure eshell/cp code is loaded - (require 'eshell) + (require 'eshell) (require 'esh-maint) (require 'em-unix) (let ((destination (file-name-as-directory (plist-get plist :publishing-directory)))) @@ -450,7 +463,6 @@ FILENAME is the filename of the file to be published." If :auto-index is set, publish the index too." (let* ((exclude-regexp (plist-get plist :exclude)) (publishing-function (or (plist-get plist :publishing-function) 'org-publish-org-to-html)) - (buf (current-buffer)) (index-p (plist-get plist :auto-index)) (index-filename (or (plist-get plist :index-filename) "index.org")) (index-function (or (plist-get plist :index-function) 'org-publish-org-index)) @@ -463,14 +475,12 @@ FILENAME is the filename of the file to be published." ;; check timestamps (when (org-publish-needed-p f) (funcall publishing-function plist f) - (org-publish-update-timestamp f)))) - ;; back to original buffer - (switch-to-buffer buf))) + (org-publish-update-timestamp f)))))) (defun org-publish-org-index (plist &optional index-filename) - "Create an index of pages in set defined by PLIST. -Optionally set the filename of the index with INDEX-FILENAME; + "Create an index of pages in set defined by PLIST. +Optionally set the filename of the index with INDEX-FILENAME; default is 'index.org'." (let* ((dir (file-name-as-directory (plist-get plist :base-directory))) (exclude-regexp (plist-get plist :exclude)) @@ -483,7 +493,7 @@ default is 'index.org'." ;; if buffer is already open, kill it to prevent error message (if index-buffer (kill-buffer index-buffer)) - (with-temp-buffer + (with-temp-buffer (while (setq f (pop files)) (let ((fn (file-name-nondirectory f))) (unless (string= fn ifn) ;; index shouldn't index itself @@ -497,19 +507,21 @@ default is 'index.org'." ;(defun org-publish-meta-index (meta-plist &optional index-filename) ; "Create an index for a metaproject." ; (let* ((plists ( - - + + ;;;; Interactive publishing functions ;;;###autoload (defun org-publish (project-name &optional force) "Publish the project PROJECT-NAME." - (interactive "sProject name: \nP") + (interactive (list (completing-read "Project name: " org-publish-project-alist + nil t) + current-prefix-arg)) (let ((org-publish-use-timestamps-flag (if force nil t)) (plists (org-publish-get-plists project-name))) (mapcar 'org-publish-plist plists))) - + ;;;###autoload (defun org-publish-current-project (&optional force) @@ -521,14 +533,14 @@ With prefix argument, force publishing all files in project." (if (not project-name) (error (format "File %s is not part of any known project." (buffer-file-name)))) (org-publish project-name))) - -;;;###autoload + +;;;###autoload (defun org-publish-current-file (&optional force) "Publish the current file. With prefix argument, force publish the file." (interactive "P") - (let ((org-publish-use-timestamps-flag + (let ((org-publish-use-timestamps-flag (if force nil t))) (org-publish-file (buffer-file-name)))) @@ -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.36b +;; Version: 4.40 ;; ;; This file is part of GNU Emacs. ;; @@ -90,6 +90,24 @@ ;; ;; Recent changes ;; -------------- +;; Version 4.40 +;; - Bug fixes. +;; +;; Version 4.39 +;; - Special tag ARCHIVE keeps a subtree closed and away from agenda lists. +;; - LaTeX code in Org-mode files can be converted to images for HTML. +;; - Bug fixes. +;; - CDLaTeX-mode features can be used in Org-mode to help inserting +;; LaTeX environment and math. +;; +;; Version 4.38 +;; - noutline.el is now required (important for XEmacs users only). +;; - Dynamic blocks. +;; - Archiving of all level 1 trees without open TODO items. +;; - Clock reports can be inserted into the file in a special section. +;; - FAQ removed from the manual, now only on the web. +;; - Bug fixes. +;; ;; Version 4.37 ;; - Clock-feature for measuring time spent on specific items. ;; - Improved emphasizing allows configuration and stacking. @@ -170,13 +188,18 @@ (eval-when-compile (require 'cl) (require 'calendar)) -(require 'outline) +;; For XEmacs, noutline is not yet provided by outline.el, so arrange for +;; the file noutline.el being loaded. +(if (featurep 'xemacs) (condition-case nil (require 'noutline))) +;; We require noutline, which might be provided in outline.el +(require 'outline) (require 'noutline) +;; Other stuff we need. (require 'time-date) (require 'easymenu) ;;; Customization variables -(defvar org-version "4.36b" +(defvar org-version "4.40" "The version number of the file org.el.") (defun org-version () (interactive) @@ -396,7 +419,8 @@ visibility is cycled." (const :tag "Everywhere except in headlines" t) )) -(defcustom org-cycle-hook '(org-optimize-window-after-visibility-change) +(defcustom org-cycle-hook '(org-cycle-hide-archived-subtrees + org-optimize-window-after-visibility-change) "Hook that is run after `org-cycle' has changed the buffer visibility. The function(s) in this hook must accept a single argument which indicates the new state that was set by the most recent `org-cycle' command. The @@ -524,6 +548,38 @@ use \\[org-ctrl-c-ctrl-c] to trigger renumbering." :tag "Org Archive" :group 'org-structure) +(defcustom org-archive-tag "ARCHIVE" + "The tag that marks a subtree as archived. +An archived subtree does not open during visibility cycling, and does +not contribute to the agenda listings." + :group 'org-archive + :group 'org-keywords + :type 'string) + +(defcustom org-agenda-skip-archived-trees t + "Non-nil means, the agenda will skip any items located in archived trees. +An archived tree is a tree marked with the tag ARCHIVE." + :group 'org-archive + :group 'org-agenda-display + :type 'boolean) + +(defcustom org-cycle-open-archived-trees nil + "Non-nil means, `org-cycle' will open archived trees. +An archived tree is a tree marked with the tag ARCHIVE. +When nil, archived trees will stay folded. You can still open them with +normal outline commands like `show-all', but not with the cycling commands." + :group 'org-archive + :group 'org-cycle + :type 'boolean) + +(defcustom org-sparse-tree-open-archived-trees nil + "Non-nil means sparse tree construction shows matches in archived trees. +When nil, matches in these trees are highlighted, but the trees are kept in +collapsed state." + :group 'org-archive + :group 'org-sparse-trees + :type 'boolean) + (defcustom org-archive-location "%s_archive::" "The location where subtrees should be archived. This string consists of two parts, separated by a double-colon. @@ -561,12 +617,12 @@ line like :type 'string) (defcustom org-archive-mark-done t - "Non-nil means, mark archived entries as DONE." + "Non-nil means, mark entries as DONE when they are moved to the archive file." :group 'org-archive :type 'boolean) (defcustom org-archive-stamp-time t - "Non-nil means, add a time stamp to archived entries. + "Non-nil means, add a time stamp to entries moved to an archive file. The time stamp will be added directly after the TODO state keyword in the first line, so it is probably best to use this in combinations with `org-archive-mark-done'." @@ -1015,12 +1071,14 @@ rather than having to type \"yes\"." (const :tag "no confirmation (dangerous)" nil))) (defconst org-file-apps-defaults-gnu - '((t . mailcap)) + '((remote . emacs) + (t . mailcap)) "Default file applications on a UNIX or GNU/Linux system. See `org-file-apps'.") (defconst org-file-apps-defaults-macosx - '((t . "open %s") + '((remote . emacs) + (t . "open %s") ("ps" . "gv %s") ("ps.gz" . "gv %s") ("eps" . "gv %s") @@ -1033,11 +1091,13 @@ for some files for which the OS does not have a good default. See `org-file-apps'.") (defconst org-file-apps-defaults-windowsnt - (list (cons t - (list (if (featurep 'xemacs) - 'mswindows-shell-execute - 'w32-shell-execute) - "open" 'file))) + (list + '(remote . emacs) + (cons t + (list (if (featurep 'xemacs) + 'mswindows-shell-execute + 'w32-shell-execute) + "open" 'file))) "Default file applications on a Windows NT system. The system \"open\" is used for most files. See `org-file-apps'.") @@ -1059,6 +1119,9 @@ files and the cdr the corresponding command. Possible values for the file identifier are \"ext\" A string identifying an extension `directory' Matches a directory + `remote' Matches a remove file, accessible through tramp or efs. + Remote files most likely should be visited through emacs + because external applications cannot handle such paths. t Default for all remaining files Possible values for the command are: @@ -1077,6 +1140,7 @@ For more examples, see the system specific constants (cons (choice :value "" (string :tag "Extension") (const :tag "Default for unrecognized files" t) + (const :tag "Remote file" remote) (const :tag "Links to a directory" directory)) (choice :value "" (const :tag "Visit with Emacs" emacs) @@ -1702,6 +1766,29 @@ N days, just insert a special line indicating the size of the gap." (const :tag "All" t) (number :tag "at most"))) +(defgroup org-latex nil + "Options for embedding LaTeX code into Org-mode" + :tag "Org LaTeX" + :group 'org) + +(defcustom org-format-latex-options + '(:foreground "Black" :background "Transparent" :scale 1.0 + :matchers ("begin" "$" "$$" "\\(" "\\[")) + "Options for creating images from LaTeX fragments. +This is a property list with the following properties: +:foreground the foreground color, for example \"Black\". +:background the background color, or \"Transparent\". +:scale a scaling factor for the size of the images +:matchers a list indicating which matchers should be used to + find LaTeX fragments. Valid members of this list are: + \"begin\" find environments + \"$\" find math expressions surrounded by $...$ + \"$$\" find math expressions surrounded by $$....$$ + \"\\(\" find math expressions surrounded by \\(...\\) + \"\\ [\" find math expressions surrounded by \\ [...\\]" + :group 'org-latex + :type 'plist) + (defgroup org-export nil "Options for exporting org-listings." :tag "Org Export" @@ -1800,6 +1887,19 @@ This option can also be set with the +OPTIONS line, e.g. \"\\n:t\"." :group 'org-export-general :type 'boolean) +(defcustom org-export-with-archived-trees 'headline + "Whether subtrees with the ARCHIVE tag should be exported. +This can have three different values +nil Do not export, pretend this tree is not present +t Do export the entire tree +headline Only export the headline, but skip the tree below it." + :group 'org-export-general + :group 'org-archive + :type '(choice + (const :tag "not at all" nil) + (const :tag "headline only" 'headline) + (const :tag "entirely" t))) + (defcustom org-export-with-timestamps t "Nil means, do not export time stamps and associated keywords." :group 'org-export @@ -1863,6 +1963,19 @@ Not all export backends support this. This option can also be set with the +OPTIONS line, e.g. \"TeX:nil\"." :group 'org-export-translation + :group 'org-latex + :type 'boolean) + +(defcustom org-export-with-LaTeX-fragments nil + "Non-nil means, convert LaTeX fragments to images when exporting to HTML. +When set, the exporter will find LaTeX environments if the \\begin line is +the first non-white thing on a line. It will also find the math delimiters +like $a=b$ and \\( a=b \\) for inline math, $$a=b$$ and \\[ a=b \\] for +display math. + +This option can also be set with the +OPTIONS line, e.g. \"LaTeX:t\"." + :group 'org-export-translation + :group 'org-latex :type 'boolean) (defcustom org-export-with-fixed-width t @@ -2202,7 +2315,7 @@ stacked Non-nil means, allow stacked styles. This works only in HTML `org-emphasis-alist') will be allowed as pre/post, aiding inside-out matching. Use customize to modify this, or restart emacs after changing it." - :group 'org-fixme + :group 'org-font-lock :set 'org-set-emph-re :type '(list (sexp :tag "Allowed chars in pre ") @@ -2216,19 +2329,23 @@ Use customize to modify this, or restart emacs after changing it." '(("*" bold "<b>" "</b>") ("/" italic "<i>" "</i>") ("_" underline "<u>" "</u>") - ("=" shadow "<code>" "</code>")) + ("=" shadow "<code>" "</code>") + ("+" (:strike-through t) "<del>" "</del>") +) "Special syntax for emphasised text. Text starting and ending with a special character will be emphasized, for example *bold*, _underlined_ and /italic/. This variable sets the marker characters, the face to bbe used by font-lock for highlighting in Org-mode emacs buffers, and the HTML tags to be used for this. Use customize to modify this, or restart emacs after changing it." - :group 'org-fixme + :group 'org-font-lock :set 'org-set-emph-re :type '(repeat (list (string :tag "Marker character") - (face :tag "Font-lock-face") + (choice + (face :tag "Font-lock-face") + (plist :tag "Face property list")) (string :tag "HTML start tag") (string :tag "HTML end tag")))) @@ -2370,6 +2487,19 @@ color of the frame." This face is only used if `org-fontify-done-headline' is set." :group 'org-faces) +(defface org-archived ; similar to shadow + (org-compatible-face + '((((class color grayscale) (min-colors 88) (background light)) + (:foreground "grey50")) + (((class color grayscale) (min-colors 88) (background dark)) + (:foreground "grey70")) + (((class color) (min-colors 8) (background light)) + (:foreground "green")) + (((class color) (min-colors 8) (background dark)) + (:foreground "yellow")))) + "Face for headline with the ARCHIVE tag." + :group 'org-faces) + (defface org-link '((((class color) (background light)) (:foreground "Purple" :underline t)) (((class color) (background dark)) (:foreground "Cyan" :underline t)) @@ -2608,7 +2738,7 @@ Also put tags into group 4 if tags are present.") (and arch (set (make-local-variable 'org-archive-location) arch)) (and int (set (make-local-variable 'org-todo-interpretation) int)) (when tags - (let (e tg c tgs) + (let (e tgs) (while (setq e (pop tags)) (cond ((equal e "{") (push '(:startgroup) tgs)) @@ -2690,6 +2820,8 @@ Also put tags into group 4 if tags are present.") (defvar org-goto-start-pos) ; dynamically scoped parameter (defvar org-time-was-given) ; dynamically scoped parameter (defvar org-ts-what) ; dynamically scoped parameter +(defvar org-current-export-file) ; dynamically scoped parameter +(defvar org-current-export-dir) ; dynamically scoped parameter (defvar mark-active) ; Emacs only, not available in XEmacs. (defvar timecnt) ; dynamically scoped parameter (defvar levels-open) ; dynamically scoped parameter @@ -2708,6 +2840,7 @@ Also put tags into group 4 if tags are present.") (defvar gnus-group-name) ; from gnus (defvar gnus-article-current) ; from gnus (defvar w3m-current-url) ; from w3m +(defvar w3m-current-title) ; from w3m (defvar mh-progs) ; from MH-E (defvar mh-current-folder) ; from MH-E (defvar mh-show-folder-buffer) ; from MH-E @@ -2723,6 +2856,8 @@ Also put tags into group 4 if tags are present.") (defvar orgtbl-mode) ; defined later in this file (defvar Info-current-file) ; from info.el (defvar Info-current-node) ; from info.el +(defvar texmathp-why) ; from texmathp.el +(defvar org-latex-regexps) ;;; Define the mode @@ -2823,8 +2958,10 @@ The following commands are available: (insert " -*- mode: org -*-\n\n")) (unless org-inhibit-startup - (if org-startup-align-all-tables - (org-table-map-tables 'org-table-align)) + (when org-startup-align-all-tables + (let ((bmp (buffer-modified-p))) + (org-table-map-tables 'org-table-align) + (set-buffer-modified-p bmp))) (if org-startup-with-deadline-check (call-interactively 'org-check-deadlines) (cond @@ -3177,6 +3314,7 @@ between words." '("^[ \t]*| *\\([#!$*_^]\\) *|" (1 'org-formula t)) (if org-format-transports-properties-p '("| *\\(<[0-9]+>\\) *" (1 'org-formula t))) + '("^\\*+ \\(.*:ARCHIVE:.*\\)" (1 'org-archived prepend)) ))) (setq org-font-lock-extra-keywords (delq nil org-font-lock-extra-keywords)) ;; Now set the full font-lock-keywords @@ -3253,7 +3391,11 @@ between words." outline-regexp)) (bob-special (and org-cycle-global-at-bob (bobp) (not (looking-at outline-regexp)))) - (org-cycle-hook (if bob-special nil org-cycle-hook)) + (org-cycle-hook + (if bob-special + (delq 'org-optimize-window-after-visibility-change + (copy-sequence org-cycle-hook)) + org-cycle-hook)) (pos (point))) (if (or bob-special (equal arg '(4))) @@ -3271,7 +3413,7 @@ between words." (call-interactively 'org-table-next-field))))) ((eq arg t) ;; Global cycling - + (cond ((and (eq last-command this-command) (eq org-cycle-global-status 'overview)) @@ -3350,6 +3492,9 @@ between words." ;; TAB emulation (buffer-read-only (org-back-to-heading)) + + ((org-try-cdlatex-tab)) + ((if (and (memq org-cycle-emulate-tab '(white whitestart)) (save-excursion (beginning-of-line 1) (looking-at "[ \t]*")) (or (and (eq org-cycle-emulate-tab 'white) @@ -3617,10 +3762,8 @@ Return t when things worked, nil when we are not in an item." t) (error nil))) (let* ((bul (match-string 0)) - (end (match-end 0)) (eow (save-excursion (beginning-of-line 1) (looking-at "[ \t]*") (match-end 0))) - (eowcol (save-excursion (goto-char eow) (current-column))) pos) (cond ((and (org-at-item-p) (<= (point) eow)) @@ -3722,9 +3865,7 @@ in the region." (replace-match up-head nil t) ;; Fixup tag positioning (and org-auto-align-tags (org-set-tags nil t)) - (if org-adapt-indentation - (org-fixup-indentation (if (> diff 1) "^ " "^ ") "" - (if (> diff 1) "^ ? ?\\S-" "^ ?\\S-"))))) + (if org-adapt-indentation (org-fixup-indentation (- diff))))) (defun org-demote () "Demote the current heading lower down the tree. @@ -3737,8 +3878,7 @@ in the region." (replace-match down-head nil t) ;; Fixup tag positioning (and org-auto-align-tags (org-set-tags nil t)) - (if org-adapt-indentation - (org-fixup-indentation "^ " (if (> diff 1) " " " ") "^\\S-")))) + (if org-adapt-indentation (org-fixup-indentation diff)))) (defun org-map-tree (fun) "Call FUN for every heading underneath the current one." @@ -3767,20 +3907,23 @@ in the region." (not (eobp))) (funcall fun))))) -;; FIXME: this does not work well with Tabulators. This has to be re-written entirely. -(defun org-fixup-indentation (from to prohibit) - "Change the indentation in the current entry by re-replacing FROM with TO. -However, if the regexp PROHIBIT matches at all, don't do anything. -This is being used to change indentation along with the length of the -heading marker. But if there are any lines which are not indented, nothing -is changed at all." +(defun org-fixup-indentation (diff) + "Change the indentation in the current entry by DIFF +However, if any line in the current entry has no indentation, or if it +would end up with no indentation after the change, nothing at all is done." (save-excursion (let ((end (save-excursion (outline-next-heading) - (point-marker)))) + (point-marker))) + (prohibit (if (> diff 0) + "^\\S-" + (concat "^ \\{0," (int-to-string (- diff)) "\\}\\S-"))) + col) (unless (save-excursion (re-search-forward prohibit end t)) - (while (re-search-forward from end t) - (replace-match to) - (beginning-of-line 2))) + (while (re-search-forward "^[ \t]+" end t) + (goto-char (match-end 0)) + (setq col (current-column)) + (if (< diff 0) (replace-match "")) + (indent-to (+ diff col)))) (move-marker end nil)))) ;;; Vertical tree motion, cutting and pasting of subtrees @@ -3984,6 +4127,14 @@ If optional TXT is given, check this string instead of the current kill." (throw 'exit nil))) t)))) +(defun org-narrow-to-subtree () + "Narrow buffer to the current subtree." + (interactive) + (save-excursion + (narrow-to-region + (progn (org-back-to-heading) (point)) + (progn (org-end-of-subtree t) (point))))) + ;;; Plain list items (defun org-at-item-p () @@ -4101,12 +4252,10 @@ If the cursor is not in an item, throw an error." "Move to the beginning of the next item in the current plain list. Error if not at a plain list, or if this is the last item in the list." (interactive) - (let (beg end ind ind1 (pos (point)) txt) + (let (ind ind1 (pos (point))) (org-beginning-of-item) - (setq beg (point)) (setq ind (org-get-indentation)) (org-end-of-item) - (setq end (point)) (setq ind1 (org-get-indentation)) (unless (and (org-at-item-p) (= ind ind1)) (goto-char pos) @@ -4116,7 +4265,7 @@ Error if not at a plain list, or if this is the last item in the list." "Move to the beginning of the previous item in the current plain list. Error if not at a plain list, or if this is the last item in the list." (interactive) - (let (beg end ind ind1 (pos (point)) txt) + (let (beg ind (pos (point))) (org-beginning-of-item) (setq beg (point)) (setq ind (org-get-indentation)) @@ -4126,7 +4275,7 @@ Error if not at a plain list, or if this is the last item in the list." (beginning-of-line 0) (if (looking-at "[ \t]*$") nil - (if (<= (setq ind1 (org-get-indentation)) ind) + (if (<= (org-get-indentation) ind) (throw 'exit t))))) (condition-case nil (org-beginning-of-item) @@ -4292,103 +4441,391 @@ with something like \"1.\" or \"2)\"." ;;; Archiving -(defun org-archive-subtree () +(defun org-archive-subtree (&optional find-done) "Move the current subtree to the archive. The archive can be a certain top-level heading in the current file, or in a different file. The tree will be moved to that location, the subtree -heading be marked DONE, and the current time will be added." - (interactive) - ;; Save all relevant TODO keyword-relatex variables - (let ((tr-org-todo-line-regexp org-todo-line-regexp) ; keep despite compiler - (tr-org-todo-keywords org-todo-keywords) - (tr-org-todo-interpretation org-todo-interpretation) - (tr-org-done-string org-done-string) - (tr-org-todo-regexp org-todo-regexp) - (tr-org-todo-line-regexp org-todo-line-regexp) - (this-buffer (current-buffer)) - file heading buffer level newfile-p) - (if (string-match "\\(.*\\)::\\(.*\\)" org-archive-location) +heading be marked DONE, and the current time will be added. + +When called with prefix argument FIND-DONE, find whole trees without any +open TODO items and archive them (after getting confirmation from the user). +If the cursor is not at a headline when this comand is called, try all level +1 trees. If the cursor is on a headline, only try the direct children of +this heading. " + (interactive "P") + (if find-done + (org-archive-all-done) + ;; Save all relevant TODO keyword-relatex variables + + (let ((tr-org-todo-line-regexp org-todo-line-regexp) ; keep despite compiler + (tr-org-todo-keywords org-todo-keywords) + (tr-org-todo-interpretation org-todo-interpretation) + (tr-org-done-string org-done-string) + (tr-org-todo-regexp org-todo-regexp) + (tr-org-todo-line-regexp org-todo-line-regexp) + (this-buffer (current-buffer)) + file heading buffer level newfile-p) + (if (string-match "\\(.*\\)::\\(.*\\)" org-archive-location) + (progn + (setq file (format (match-string 1 org-archive-location) + (file-name-nondirectory buffer-file-name)) + heading (match-string 2 org-archive-location))) + (error "Invalid `org-archive-location'")) + (if (> (length file) 0) + (setq newfile-p (not (file-exists-p file)) + buffer (find-file-noselect file)) + (setq buffer (current-buffer))) + (unless buffer + (error "Cannot access file \"%s\"" file)) + (if (and (> (length heading) 0) + (string-match "^\\*+" heading)) + (setq level (match-end 0)) + (setq heading nil level 0)) + (save-excursion + ;; We first only copy, in case something goes wrong + ;; we need to protect this-command, to avoid kill-region sets it, + ;; which would lead to duplication of subtrees + (let (this-command) (org-copy-subtree)) + (set-buffer buffer) + ;; Enforce org-mode for the archive buffer + (if (not (eq major-mode 'org-mode)) + ;; Force the mode for future visits. + (let ((org-insert-mode-line-in-empty-file t)) + (call-interactively 'org-mode))) + (when newfile-p + (goto-char (point-max)) + (insert (format "\nArchived entries from file %s\n\n" + (buffer-file-name this-buffer)))) + ;; Force the TODO keywords of the original buffer + (let ((org-todo-line-regexp tr-org-todo-line-regexp) + (org-todo-keywords tr-org-todo-keywords) + (org-todo-interpretation tr-org-todo-interpretation) + (org-done-string tr-org-done-string) + (org-todo-regexp tr-org-todo-regexp) + (org-todo-line-regexp tr-org-todo-line-regexp)) + (goto-char (point-min)) + (if heading + (progn + (if (re-search-forward + (concat "\\(^\\|\r\\)" + (regexp-quote heading) "[ \t]*\\($\\|\r\\)") + nil t) + (goto-char (match-end 0)) + ;; Heading not found, just insert it at the end + (goto-char (point-max)) + (or (bolp) (insert "\n")) + (insert "\n" heading "\n") + (end-of-line 0)) + ;; Make the subtree visible + (show-subtree) + (org-end-of-subtree t) + (skip-chars-backward " \t\r\n]") + (and (looking-at "[ \t\r\n]*") + (replace-match "\n\n"))) + ;; No specific heading, just go to end of file. + (goto-char (point-max)) (insert "\n")) + ;; Paste + (org-paste-subtree (1+ level)) + ;; Mark the entry as done, i.e. set to last work in org-todo-keywords + (if org-archive-mark-done + (org-todo (length org-todo-keywords))) + ;; Move cursor to right after the TODO keyword + (when org-archive-stamp-time + (beginning-of-line 1) + (looking-at org-todo-line-regexp) + (goto-char (or (match-end 2) (match-beginning 3))) + (insert "(" (format-time-string (cdr org-time-stamp-formats) + (org-current-time)) + ")")) + ;; Save the buffer, if it is not the same buffer. + (if (not (eq this-buffer buffer)) (save-buffer)))) + ;; Here we are back in the original buffer. Everything seems to have + ;; worked. So now cut the tree and finish up. + (let (this-command) (org-cut-subtree)) + (if (and (not (eobp)) (looking-at "[ \t]*$")) (kill-line)) + (message "Subtree archived %s" + (if (eq this-buffer buffer) + (concat "under heading: " heading) + (concat "in file: " (abbreviate-file-name file))))))) + +(defun org-archive-all-done (&optional tag) + "Archive sublevels of the current tree without open TODO items. +If the cursor is not on a headline, try all level 1 trees. If +it is on a headline, try all direct children. +When TAG is non-nil, don't move trees, but mark them with the ARCHIVE tag." + (let ((re (concat "^\\*+ +" org-not-done-regexp)) re1 + (rea (concat ".*:" org-archive-tag ":")) + (begm (make-marker)) + (endm (make-marker)) + (question (if tag "Set ARCHIVE tag (no open TODO items)? " + "Move subtree to archive (no open TODO items)? ")) + beg end (cntarch 0)) + (if (org-on-heading-p) (progn - (setq file (format (match-string 1 org-archive-location) - (file-name-nondirectory buffer-file-name)) - heading (match-string 2 org-archive-location))) - (error "Invalid `org-archive-location'")) - (if (> (length file) 0) - (setq newfile-p (not (file-exists-p file)) - buffer (find-file-noselect file)) - (setq buffer (current-buffer))) - (unless buffer - (error "Cannot access file \"%s\"" file)) - (if (and (> (length heading) 0) - (string-match "^\\*+" heading)) - (setq level (match-end 0)) - (setq heading nil level 0)) + (setq re1 (concat "^" (regexp-quote + (make-string + (1+ (- (match-end 0) (match-beginning 0))) + ?*)) + " ")) + (move-marker begm (point)) + (move-marker endm (org-end-of-subtree))) + (setq re1 "^* ") + (move-marker begm (point-min)) + (move-marker endm (point-max))) (save-excursion - ;; We first only copy, in case something goes wrong - ;; we need to protect this-command, to avoid kill-region sets it, - ;; which would lead to duplication of subtrees - (let (this-command) (org-copy-subtree)) - (set-buffer buffer) - ;; Enforce org-mode for the archive buffer - (if (not (eq major-mode 'org-mode)) - ;; Force the mode for future visits. - (let ((org-insert-mode-line-in-empty-file t)) - (call-interactively 'org-mode))) - (when newfile-p - (goto-char (point-max)) - (insert (format "\nArchived entries from file %s\n\n" - (buffer-file-name this-buffer)))) - ;; Force the TODO keywords of the original buffer - (let ((org-todo-line-regexp tr-org-todo-line-regexp) - (org-todo-keywords tr-org-todo-keywords) - (org-todo-interpretation tr-org-todo-interpretation) - (org-done-string tr-org-done-string) - (org-todo-regexp tr-org-todo-regexp) - (org-todo-line-regexp tr-org-todo-line-regexp)) - (goto-char (point-min)) - (if heading - (progn - (if (re-search-forward - (concat "\\(^\\|\r\\)" - (regexp-quote heading) "[ \t]*\\($\\|\r\\)") - nil t) - (goto-char (match-end 0)) - ;; Heading not found, just insert it at the end - (goto-char (point-max)) - (or (bolp) (insert "\n")) - (insert "\n" heading "\n") - (end-of-line 0)) - ;; Make the subtree visible - (show-subtree) - (org-end-of-subtree t) - (skip-chars-backward " \t\r\n]") - (and (looking-at "[ \t\r\n]*") - (replace-match "\n\n"))) - ;; No specific heading, just go to end of file. - (goto-char (point-max)) (insert "\n")) - ;; Paste - (org-paste-subtree (1+ level)) - ;; Mark the entry as done, i.e. set to last work in org-todo-keywords - (if org-archive-mark-done - (org-todo (length org-todo-keywords))) - ;; Move cursor to right after the TODO keyword - (when org-archive-stamp-time - (beginning-of-line 1) - (looking-at org-todo-line-regexp) - (goto-char (or (match-end 2) (match-beginning 3))) - (insert "(" (format-time-string (cdr org-time-stamp-formats) - (org-current-time)) - ")")) - ;; Save the buffer, if it is not the same buffer. - (if (not (eq this-buffer buffer)) (save-buffer)))) - ;; Here we are back in the original buffer. Everything seems to have - ;; worked. So now cut the tree and finish up. - (let (this-command) (org-cut-subtree)) - (if (and (not (eobp)) (looking-at "[ \t]*$")) (kill-line)) - (message "Subtree archived %s" - (if (eq this-buffer buffer) - (concat "under heading: " heading) - (concat "in file: " (abbreviate-file-name file)))))) + (goto-char begm) + (while (re-search-forward re1 endm t) + beg (match-beginning 0) + end (save-excursion (org-end-of-subtree t) (point))) + (goto-char beg) + (if (re-search-forward re end t) + (goto-char end) + (goto-char beg) + (if (and (or (not tag) (not (looking-at rea))) + (y-or-n-p question)) + (progn + (if tag + (org-toggle-tag org-archive-tag 'on) + (org-archive-subtree)) + (setq cntarch (1+ cntarch))) + (goto-char end)))) + (message "%d trees archived" cntarch))) + + +(defun org-cycle-hide-archived-subtrees (state) + "Re-hide all archived subtrees after a visibility state change." + (when (and (not org-cycle-open-archived-trees) + (not (memq state '(overview folded)))) + (save-excursion + (let* ((globalp (memq state '(contents all))) + (beg (if globalp (point-min) (point))) + (end (if globalp (point-max) (org-end-of-subtree)))) + (org-hide-archived-subtrees beg end))))) + +(defun org-hide-archived-subtrees (beg end) + "Re-hide all archived subtrees after a visibility state change." + (save-excursion + (let* ((re (concat ":" org-archive-tag ":"))) + (goto-char beg) + (while (re-search-forward re end t) + (and (org-on-heading-p) (hide-subtree)) + (org-end-of-subtree))))) + +(defun org-toggle-tag (tag &optional onoff) + "Toggle the tag TAG for the current line. +If ONOFF is `on' or `off', don't toggle but set to this state." + (unless (org-on-heading-p) (error "Not on headling")) + (let (res current) + (save-excursion + (beginning-of-line) + (if (re-search-forward "[ \t]:\\([a-zA-Z0-9_@:]+\\):[ \t]*$" + (point-at-eol) t) + (progn + (setq current (match-string 1)) + (replace-match "")) + (setq current "")) + (setq current (nreverse (org-split-string current ":"))) + (cond + ((eq onoff 'on) + (setq res t) + (or (member tag current) (push tag current))) + ((eq onoff 'off) + (or (not (member tag current)) (setq current (delete tag current)))) + (t (if (member tag current) + (setq current (delete tag current)) + (setq res t) + (push tag current)))) + (end-of-line 1) + (when current + (insert " :" (mapconcat 'identity (nreverse current) ":") ":")) + (org-set-tags nil t)) + res)) + +(defun org-toggle-archive-tag (&optional arg) + "Toggle the archive tag for the current headline. +With prefix ARG, check all children of current headline and offer tagging +the children that do not contain any open TODO items." + (interactive "P") + (if arg + (org-archive-all-done 'tag) + (let (set) + (save-excursion + (org-back-to-heading t) + (setq set (org-toggle-tag org-archive-tag)) + (when set (hide-subtree))) + (and set (beginning-of-line 1)) + (message "Subtree %s" (if set "archived" "unarchived"))))) + +(defun org-prepare-agenda-buffers (files) + "Create buffers for all agenda files, protect archived trees and comments." + (let ((pa '(:org-archived t)) + (pc '(:org-comment t)) + (pall '(:org-archived t :org-comment t)) + (rea (concat ":" org-archive-tag ":")) + file re) + (save-excursion + (while (setq file (pop files)) + (org-check-agenda-file file) + (set-buffer (org-get-agenda-file-buffer file)) + (widen) + (save-excursion + (remove-text-properties (point-min) (point-max) pall) + (when org-agenda-skip-archived-trees + (goto-char (point-min)) + (while (re-search-forward rea nil t) + (if (org-on-heading-p) + (add-text-properties (point-at-bol) (org-end-of-subtree) pa)))) + (goto-char (point-min)) + (setq re (concat "^\\*+ +" org-comment-string "\\>")) + (while (re-search-forward re nil t) + (add-text-properties + (match-beginning 0) (org-end-of-subtree) pc))))))) + +(defun org-agenda-skip () + "Throw to `:skip' in places that should be skipped." + (let ((p (point-at-bol))) + (and org-agenda-skip-archived-trees + (get-text-property p :org-archived) + (org-end-of-subtree) + (throw :skip t)) + (and (get-text-property p :org-comment) + (org-end-of-subtree) + (throw :skip t)) + (if (equal (char-after p) ?#) (throw :skip t)))) + +(defun org-agenda-toggle-archive-tag () + "Toggle the archive tag for the current entry." + (interactive) + (org-agenda-check-no-diary) + (org-agenda-show) ;;; FIXME This is a stupid hack and should not be needed + (let* ((hdmarker (or (get-text-property (point) 'org-hd-marker) + (org-agenda-error))) + (buffer (marker-buffer hdmarker)) + (pos (marker-position hdmarker)) + (buffer-read-only nil) + newhead) + (with-current-buffer buffer + (widen) + (goto-char pos) + (org-show-hidden-entry) + (save-excursion + (and (outline-next-heading) + (org-flag-heading nil))) ; show the next heading + (call-interactively 'org-toggle-archive-tag) + (end-of-line 1) + (setq newhead (org-get-heading))) + (org-agenda-change-all-lines newhead hdmarker) + (beginning-of-line 1))) + +;;; Dynamic blocks + +(defun org-find-dblock (name) + "Find the first dynamic block with name NAME in the buffer. +If not found, stay at current position and return nil." + (let (pos) + (save-excursion + (goto-char (point-min)) + (setq pos (and (re-search-forward (concat "^#\\+BEGIN:[ \t]+" name "\\>") + nil t) + (match-beginning 0)))) + (if pos (goto-char pos)) + pos)) + +(defconst org-dblock-start-re + "^#\\+BEGIN:[ \t]+\\(\\S-+\\)[ \t]+\\(.*\\)" + "Matches the startline of a dynamic block, with parameters.") + +(defconst org-dblock-end-re "^#\\+END\\([: \t\r\n]\\|$\\)" + "Matches the end of a dyhamic block.") + +(defun org-create-dblock (plist) + "Create a dynamic block section, with parameters taken from PLIST. +PLIST must containe a :name entry which is used as name of the block." + (unless (bolp) (newline)) + (let ((name (plist-get plist :name))) + (insert "#+BEGIN: " name) + (while plist + (if (eq (car plist) :name) + (setq plist (cddr plist)) + (insert " " (prin1-to-string (pop plist))))) + (insert "\n\n#+END:\n") + (beginning-of-line -2))) + +(defun org-prepare-dblock () + "Prepare dynamic block for refresh. +This empties the block, puts the cursor at the insert position and returns +the property list including an extra property :name with the block name." + (unless (looking-at org-dblock-start-re) + (error "Not at a dynamic block")) + (let* ((begdel (1+ (match-end 0))) + (name (match-string 1)) + (params (append (list :name name) + (read (concat "(" (match-string 2) ")"))))) + (unless (re-search-forward org-dblock-end-re nil t) + (error "Dynamic block not terminated")) + (delete-region begdel (match-beginning 0)) + (goto-char begdel) + (open-line 1) + params)) + +(defun org-map-dblocks (&optional command) + "Apply COMMAND to all dynamic blocks in the current buffer. +If COMMAND is not given, use `org-update-dblock'." + (let ((cmd (or command 'org-update-dblock)) + pos) + (save-excursion + (goto-char (point-min)) + (while (re-search-forward org-dblock-start-re nil t) + (goto-char (setq pos (match-beginning 0))) + (condition-case nil + (funcall cmd) + (error (message "Error during update of dynamic block"))) + (goto-char pos) + (unless (re-search-forward org-dblock-end-re nil t) + (error "Dynamic block not terminated")))))) + +(defun org-dblock-update (&optional arg) + "User command for updating dynamic blocks. +Update the dynamic block at point. With prefix ARG, update all dynamic +blocks in the buffer." + (interactive "P") + (if arg + (org-update-all-dblocks) + (or (looking-at org-dblock-start-re) + (org-beginning-of-dblock)) + (org-update-dblock))) + +(defun org-update-dblock () + "Update the dynamic block at point +This means to empty the block, parse for parameters and then call +the correct writing function." + (let* ((pos (point)) + (params (org-prepare-dblock)) + (name (plist-get params :name)) + (cmd (intern (concat "org-dblock-write:" name)))) + (funcall cmd params) + (goto-char pos))) + +(defun org-beginning-of-dblock () + "Find the beginning of the dynamic block at point. +Error if there is no scuh block at point." + (let ((pos (point)) + beg) + (end-of-line 1) + (if (and (re-search-backward org-dblock-start-re nil t) + (setq beg (match-beginning 0)) + (re-search-forward org-dblock-end-re nil t) + (> (match-end 0) pos)) + (goto-char beg) + (goto-char pos) + (error "Not in a dynamic block")))) + +(defun org-update-all-dblocks () + "Update all dynamic blocks in the buffer. +This function can be used in a hook." + (when (eq major-mode 'org-mode) + (org-map-dblocks 'org-update-dblock))) + ;;; Completion @@ -4662,9 +5099,8 @@ be removed." (format-time-string (car org-time-stamp-formats) time)) (setq what nil)) (save-excursion - (let (beg end col list elt (buffer-invisibility-spec nil) ts) + (let (col list elt (buffer-invisibility-spec nil) ts) (org-back-to-heading t) - (setq beg (point)) (looking-at (concat outline-regexp "\\( *\\)[^\r\n]*")) (goto-char (match-end 1)) (setq col (current-column)) @@ -4734,6 +5170,8 @@ that the match should indeed be shown." (org-show-hierarchy-above)))) (org-add-hook 'before-change-functions 'org-remove-occur-highlights nil 'local) + (unless org-sparse-tree-open-archived-trees + (org-hide-archived-subtrees (point-min) (point-max))) (run-hooks 'org-occur-hook) (if (interactive-p) (message "%d match(es) for regexp %s" cnt regexp)) @@ -4775,24 +5213,33 @@ that the match should indeed be shown." (if (featurep 'xemacs) (set-extent-property ovl prop value) (overlay-put ovl prop value))) +(defun org-overlays-at (pos) + (if (featurep 'xemacs) (extents-at pos) (overlays-at pos))) +(defun org-overlay-start (o) + (if (featurep 'xemacs) (extent-start-position o) (overlay-start o))) +(defun org-overlay-end (o) + (if (featurep 'xemacs) (extent-end-position o) (overlay-end o))) (defvar org-occur-highlights nil) +(make-variable-buffer-local 'org-occur-highlights) (defun org-highlight-new-match (beg end) "Highlight from BEG to END and mark the highlight is an occur headline." (let ((ov (org-make-overlay beg end))) (org-overlay-put ov 'face 'secondary-selection) (push ov org-occur-highlights))) +(defvar org-inhibit-highlight-removal nil) (defun org-remove-occur-highlights (&optional beg end noremove) "Remove the occur highlights from the buffer. BEG and END are ignored. If NOREMOVE is nil, remove this function from the `before-change-functions' in the current buffer." (interactive) - (mapc 'org-delete-overlay org-occur-highlights) - (setq org-occur-highlights nil) - (unless noremove - (remove-hook 'before-change-functions - 'org-remove-occur-highlights 'local))) + (unless org-inhibit-highlight-removal + (mapc 'org-delete-overlay org-occur-highlights) + (setq org-occur-highlights nil) + (unless noremove + (remove-hook 'before-change-functions + 'org-remove-occur-highlights 'local)))) ;;; Priorities @@ -5449,15 +5896,16 @@ If there is no running clock, throw an error, unless FAIL-QUIETLY is set." "Sum the times for each subtree. Puts the resulting times in minutes as a text property on each headline." (interactive) - (remove-text-properties (point-min) (point-max) '(:org-clock-minutes t)) - (let* ((re (concat "^\\(\\*+\\)[ \t]\\|^[ \t]*" + (let* ((bmp (buffer-modified-p)) + (re (concat "^\\(\\*+\\)[ \t]\\|^[ \t]*" org-clock-string ".*=>[ \t]*\\([0-9]+\\):\\([0-9]+\\)[ \t]*$")) (lmax 30) (ltimes (make-vector lmax 0)) (t1 0) (level 0) - (lastlevel 0) time) + time) + (remove-text-properties (point-min) (point-max) '(:org-clock-minutes t)) (save-excursion (goto-char (point-max)) (while (re-search-backward re nil t) @@ -5475,7 +5923,8 @@ Puts the resulting times in minutes as a text property on each headline." (aset ltimes l 0)) (goto-char (match-beginning 0)) (put-text-property (point) (point-at-eol) :org-clock-minutes time)))) - (setq org-clock-file-total-minutes (aref ltimes 0))))) + (setq org-clock-file-total-minutes (aref ltimes 0))) + (set-buffer-modified-p bmp))) (defun org-clock-display (&optional total-only) "Show subtree times in the entire buffer. @@ -5500,6 +5949,8 @@ in the echo area." (message "Total file time: %d:%02d (%d hours and %d minutes)" h m h m))) (defvar org-clock-overlays nil) +(make-variable-buffer-local 'org-clock-overlays) + (defun org-put-clock-overlay (time &optional level) "Put an overlays on the current line, displaying TIME. If LEVEL is given, prefix time with a corresponding number of stars. @@ -5510,11 +5961,11 @@ will be easy to remove." (off 0) ov tx) (move-to-column c) - (if (eolp) (setq off 1)) (unless (eolp) (skip-chars-backward "^ \t")) (skip-chars-backward " \t") - (setq ov (org-make-overlay (- (point) off) (point-at-eol)) - tx (concat (make-string (+ off (max 0 (- c (current-column)))) ?.) + (setq ov (org-make-overlay (1- (point)) (point-at-eol)) + tx (concat (buffer-substring (1- (point)) (point)) + (make-string (+ off (max 0 (- c (current-column)))) ?.) (org-add-props (format "%s %2d:%02d%s" (make-string l ?*) h m (make-string (- 10 l) ?\ )) @@ -5528,11 +5979,12 @@ will be easy to remove." BEG and END are ignored. If NOREMOVE is nil, remove this function from the `before-change-functions' in the current buffer." (interactive) - (mapc 'org-delete-overlay org-clock-overlays) - (setq org-clock-overlays nil) - (unless noremove - (remove-hook 'before-change-functions - 'org-remove-clock-overlays 'local))) + (unless org-inhibit-highlight-removal + (mapc 'org-delete-overlay org-clock-overlays) + (setq org-clock-overlays nil) + (unless noremove + (remove-hook 'before-change-functions + 'org-remove-clock-overlays 'local)))) (defun org-clock-out-if-current () "Clock out if the current entry contains the running clock. @@ -5557,6 +6009,112 @@ If yes, offer to stop it and to save the buffer with the changes." (when (y-or-n-p "Save changed buffer?") (save-buffer)))) +(defun org-clock-report () + "Create a table containing a report about clocked time. +If the buffer contains lines +#+BEGIN: clocktable :maxlevel 3 :emphasize nil + +#+END: clocktable +then the table will be inserted between these lines, replacing whatever +is was there before. If these lines are not in the buffer, the table +is inserted at point, surrounded by the special lines. +The BEGIN line can contain parameters. Allowed are: +:maxlevel The maximum level to be included in the table. Default is 3. +:emphasize t/nil, if levell 1 and level 2 should be bold/italic in the table." + (interactive) + (org-remove-clock-overlays) + (unless (org-find-dblock "clocktable") + (org-create-dblock (list :name "clocktable" + :maxlevel 2 :emphasize nil))) + (org-update-dblock)) + +(defun org-dblock-write:clocktable (params) + "Write the standard clocktable." + (let ((hlchars '((1 . "*") (2 . ?/))) + (emph nil) + (ins (make-marker)) + ipos time h m p level hlc hdl maxlevel) + (setq maxlevel (or (plist-get params :maxlevel) 3) + emph (plist-get params :emphasize)) + (move-marker ins (point)) + (setq ipos (point)) + (insert-before-markers "Clock summary at [" + (substring + (format-time-string (cdr org-time-stamp-formats)) + 1 -1) + "]\n|L|Headline|Time|\n") + (org-clock-sum) + (setq h (/ org-clock-file-total-minutes 60) + m (- org-clock-file-total-minutes (* 60 h))) + (insert-before-markers "|-\n|0|" "*Total file time*| " + (format "*%d:%02d*" h m) + "|\n") + (goto-char (point-min)) + (while (setq p (next-single-property-change (point) :org-clock-minutes)) + (goto-char p) + (when (setq time (get-text-property p :org-clock-minutes)) + (beginning-of-line 1) + (when (and (looking-at "\\(\\*+\\)[ \t]+\\(.*?\\)\\([ \t]+:[0-9a-zA-Z_@:]+:\\)?[ \t]*$") + (setq level (- (match-end 1) (match-beginning 1))) + (<= level maxlevel)) + (setq hlc (if emph (or (cdr (assoc level hlchars)) "") "") + hdl (match-string 2) + h (/ time 60) + m (- time (* 60 h))) + (save-excursion + (goto-char ins) + (if (= level 1) (insert-before-markers "|-\n")) + (insert-before-markers + "| " (int-to-string level) "|" hlc hdl hlc " |" + (make-string (1- level) ?|) + hlc + (format "%d:%02d" h m) + hlc + " |\n"))))) + (goto-char ins) + (backward-delete-char 1) + (goto-char ipos) + (skip-chars-forward "^|") + (org-table-align))) + +(defun org-collect-clock-time-entries () + "Return an internal list with clocking information. +This list has one entry for each CLOCK interval. +FIXME: describe the elements." + (interactive) + (let ((re (concat "^[ \t]*" org-clock-string + " *\\[\\(.*?\\)\\]--\\[\\(.*?\\)\\]")) + rtn beg end next cont level title total closedp leafp + clockpos titlepos h m donep) + (save-excursion + (org-clock-sum) + (goto-char (point-min)) + (while (re-search-forward re nil t) + (setq clockpos (match-beginning 0) + beg (match-string 1) end (match-string 2) + cont (match-end 0)) + (setq beg (apply 'encode-time (org-parse-time-string beg)) + end (apply 'encode-time (org-parse-time-string end))) + (org-back-to-heading t) + (setq donep (org-entry-is-done-p)) + (setq titlepos (point) + total (or (get-text-property (1+ (point)) :org-clock-minutes) 0) + h (/ total 60) m (- total (* 60 h)) + total (cons h m)) + (looking-at "\\(\\*+\\) +\\(.*\\)") + (setq level (- (match-end 1) (match-beginning 1)) + title (org-match-string-no-properties 2)) + (save-excursion (outline-next-heading) (setq next (point))) + (setq closedp (re-search-forward org-closed-time-regexp next t)) + (goto-char next) + (setq leafp (and (looking-at "^\\*+ ") + (<= (- (match-end 0) (point)) level))) + (push (list beg end clockpos closedp donep + total title titlepos level leafp) + rtn) + (goto-char cont))) + (nreverse rtn))) + ;;; Agenda, and Diary Integration ;;; Define the mode @@ -5616,6 +6174,7 @@ The following commands are available: (define-key org-agenda-mode-map "o" 'delete-other-windows) (define-key org-agenda-mode-map "L" 'org-agenda-recenter) (define-key org-agenda-mode-map "t" 'org-agenda-todo) +(define-key org-agenda-mode-map "a" 'org-agenda-toggle-archive-tag) (define-key org-agenda-mode-map ":" 'org-agenda-set-tags) (define-key org-agenda-mode-map "." 'org-agenda-goto-today) (define-key org-agenda-mode-map "d" 'org-agenda-day-view) @@ -5983,6 +6542,7 @@ dates." (past t) args s e rtn d emptyp) + (org-prepare-agenda-buffers org-agenda-files) (setq org-agenda-redo-command (list 'progn (list 'switch-to-buffer-other-window (current-buffer)) @@ -6077,6 +6637,7 @@ NDAYS defaults to `org-agenda-ndays'." (day-numbers (list start)) (inhibit-redisplay t) s e rtn rtnall file date d start-pos end-pos todayp nd) + (org-prepare-agenda-buffers files) (setq org-agenda-redo-command (list 'org-agenda-list (list 'quote include-all) start-day ndays t)) ;; Make the list of days @@ -6212,6 +6773,7 @@ for a keyword. A numeric prefix directly selects the Nth keyword in '(org-todo-list (or current-prefix-arg last-arg) t)) (setq files (org-agenda-files) rtnall nil) + (org-prepare-agenda-buffers files) (while (setq file (pop files)) (catch 'nextfile (org-check-agenda-file file) @@ -6820,8 +7382,11 @@ the documentation of `org-diary'." ee txt) (goto-char (point-min)) (while (re-search-forward regexp nil t) - (when (not (and org-agenda-todo-ignore-scheduled - (save-match-data (looking-at sched-re)))) + (catch :skip + (and org-agenda-todo-ignore-scheduled + (looking-at sched-re) + (throw :skip nil)) + (org-agenda-skip) (goto-char (match-beginning 1)) (setq marker (org-agenda-new-marker (1+ (match-beginning 0))) category (org-get-category) @@ -6833,14 +7398,14 @@ the documentation of `org-diary'." (- org-todo-kwd-max-priority -2 (length (member (match-string 2) org-todo-keywords))) - 1))) + 1))) (org-add-props txt props 'org-marker marker 'org-hd-marker marker 'priority priority 'category category) - (push txt ee)) - (if org-agenda-todo-list-sublevels - (goto-char (match-end 1)) - (org-end-of-subtree 'invisible))) + (push txt ee) + (if org-agenda-todo-list-sublevels + (goto-char (match-end 1)) + (org-end-of-subtree 'invisible)))) (nreverse ee))) (defconst org-agenda-no-heading-message @@ -6866,50 +7431,51 @@ the documentation of `org-diary'." ee txt timestr tags) (goto-char (point-min)) (while (re-search-forward regexp nil t) - (if (not (save-match-data (org-at-date-range-p))) - (progn - (setq marker (org-agenda-new-marker (match-beginning 0)) - category (org-get-category (match-beginning 0)) - tmp (buffer-substring (max (point-min) - (- (match-beginning 0) - org-ds-keyword-length)) - (match-beginning 0)) - timestr (buffer-substring (match-beginning 0) (point-at-eol)) - deadlinep (string-match org-deadline-regexp tmp) - scheduledp (string-match org-scheduled-regexp tmp) - donep (org-entry-is-done-p)) - (if (string-match ">" timestr) - ;; substring should only run to end of time stamp - (setq timestr (substring timestr 0 (match-end 0)))) - (save-excursion - (if (re-search-backward "\\(^\\|\r\\)\\*+" nil t) - (progn - (goto-char (match-end 1)) - (setq hdmarker (org-agenda-new-marker) - tags (org-get-tags-at)) - (looking-at "\\*+[ \t]*\\([^\r\n]+\\)") - (setq txt (org-format-agenda-item - (format "%s%s" - (if deadlinep "Deadline: " "") - (if scheduledp "Scheduled: " "")) - (match-string 1) category tags timestr))) - (setq txt org-agenda-no-heading-message)) - (setq priority (org-get-priority txt)) - (org-add-props txt props - 'org-marker marker 'org-hd-marker hdmarker) - (if deadlinep - (org-add-props txt nil - 'face (if donep 'org-done 'org-warning) - 'undone-face 'org-warning 'done-face 'org-done - 'category category 'priority (+ 100 priority)) - (if scheduledp - (org-add-props txt nil - 'face 'org-scheduled-today - 'undone-face 'org-scheduled-today 'done-face 'org-done - 'category category 'priority (+ 99 priority)) - (org-add-props txt nil 'priority priority 'category category))) - (push txt ee)) - (outline-next-heading)))) + (catch :skip + (and (save-match-data (org-at-date-range-p)) (throw :skip nil)) + (org-agenda-skip) + (setq marker (org-agenda-new-marker (match-beginning 0)) + category (org-get-category (match-beginning 0)) + tmp (buffer-substring (max (point-min) + (- (match-beginning 0) + org-ds-keyword-length)) + (match-beginning 0)) + timestr (buffer-substring (match-beginning 0) (point-at-eol)) + deadlinep (string-match org-deadline-regexp tmp) + scheduledp (string-match org-scheduled-regexp tmp) + donep (org-entry-is-done-p)) + (if (string-match ">" timestr) + ;; substring should only run to end of time stamp + (setq timestr (substring timestr 0 (match-end 0)))) + (save-excursion + (if (re-search-backward "\\(^\\|\r\\)\\*+" nil t) + (progn + (goto-char (match-end 1)) + (setq hdmarker (org-agenda-new-marker) + tags (org-get-tags-at)) + (looking-at "\\*+[ \t]*\\([^\r\n]+\\)") + (setq txt (org-format-agenda-item + (format "%s%s" + (if deadlinep "Deadline: " "") + (if scheduledp "Scheduled: " "")) + (match-string 1) category tags timestr))) + (setq txt org-agenda-no-heading-message)) + (setq priority (org-get-priority txt)) + (org-add-props txt props + 'org-marker marker 'org-hd-marker hdmarker) + (if deadlinep + (org-add-props txt nil + 'face (if donep 'org-done 'org-warning) + 'undone-face 'org-warning 'done-face 'org-done + 'category category 'priority (+ 100 priority)) + (if scheduledp + (org-add-props txt nil + 'face 'org-scheduled-today + 'undone-face 'org-scheduled-today 'done-face 'org-done + 'category category 'priority (+ 99 priority)) + (org-add-props txt nil 'priority priority 'category category))) + (push txt ee)) + (outline-next-heading))) (nreverse ee))) (defun org-agenda-get-closed () @@ -6933,35 +7499,35 @@ the documentation of `org-diary'." ee txt timestr) (goto-char (point-min)) (while (re-search-forward regexp nil t) - (if (not (save-match-data (org-at-date-range-p))) - (progn - (setq marker (org-agenda-new-marker (match-beginning 0)) - closedp (equal (match-string 1) org-closed-string) - category (org-get-category (match-beginning 0)) - timestr (buffer-substring (match-beginning 0) (point-at-eol)) - ;; donep (org-entry-is-done-p) - ) - (if (string-match "\\]" timestr) - ;; substring should only run to end of time stamp - (setq timestr (substring timestr 0 (match-end 0)))) - (save-excursion - (if (re-search-backward "\\(^\\|\r\\)\\*+" nil t) - (progn - (goto-char (match-end 1)) - (setq hdmarker (org-agenda-new-marker) - tags (org-get-tags-at)) - (looking-at "\\*+[ \t]*\\([^\r\n]+\\)") - (setq txt (org-format-agenda-item - (if closedp "Closed: " "Clocked: ") - (match-string 1) category tags timestr))) - (setq txt org-agenda-no-heading-message)) - (setq priority 100000) - (org-add-props txt props - 'org-marker marker 'org-hd-marker hdmarker 'face 'org-done - 'priority priority 'category category - 'undone-face 'org-warning 'done-face 'org-done) - (push txt ee)) - (outline-next-heading)))) + (catch :skip + (org-agenda-skip) + (setq marker (org-agenda-new-marker (match-beginning 0)) + closedp (equal (match-string 1) org-closed-string) + category (org-get-category (match-beginning 0)) + timestr (buffer-substring (match-beginning 0) (point-at-eol)) + ;; donep (org-entry-is-done-p) + ) + (if (string-match "\\]" timestr) + ;; substring should only run to end of time stamp + (setq timestr (substring timestr 0 (match-end 0)))) + (save-excursion + (if (re-search-backward "\\(^\\|\r\\)\\*+" nil t) + (progn + (goto-char (match-end 1)) + (setq hdmarker (org-agenda-new-marker) + tags (org-get-tags-at)) + (looking-at "\\*+[ \t]*\\([^\r\n]+\\)") + (setq txt (org-format-agenda-item + (if closedp "Closed: " "Clocked: ") + (match-string 1) category tags timestr))) + (setq txt org-agenda-no-heading-message)) + (setq priority 100000) + (org-add-props txt props + 'org-marker marker 'org-hd-marker hdmarker 'face 'org-done + 'priority priority 'category category + 'undone-face 'org-warning 'done-face 'org-done) + (push txt ee)) + (outline-next-heading))) (nreverse ee))) (defun org-agenda-get-deadlines () @@ -6980,41 +7546,43 @@ the documentation of `org-diary'." ee txt head face) (goto-char (point-min)) (while (re-search-forward regexp nil t) - (setq pos (1- (match-beginning 1)) - d2 (time-to-days - (org-time-string-to-time (match-string 1))) - diff (- d2 d1)) - ;; When to show a deadline in the calendar: - ;; If the expiration is within wdays warning time. - ;; Past-due deadlines are only shown on the current date - (if (and (< diff wdays) todayp (not (= diff 0))) - (save-excursion - (setq category (org-get-category)) - (if (re-search-backward "\\(^\\|\r\\)\\*+[ \t]*" nil t) - (progn - (goto-char (match-end 0)) - (setq pos1 (match-end 1)) - (setq tags (org-get-tags-at pos1)) - (setq head (buffer-substring-no-properties - (point) - (progn (skip-chars-forward "^\r\n") - (point)))) - (if (string-match org-looking-at-done-regexp head) - (setq txt nil) - (setq txt (org-format-agenda-item - (format "In %3d d.: " diff) head category tags)))) - (setq txt org-agenda-no-heading-message)) - (when txt - (setq face (cond ((<= diff 0) 'org-warning) - ((<= diff 5) 'org-upcoming-deadline) - (t nil))) - (org-add-props txt props - 'org-marker (org-agenda-new-marker pos) - 'org-hd-marker (org-agenda-new-marker pos1) - 'priority (+ (- 10 diff) (org-get-priority txt)) - 'category category - 'face face 'undone-face face 'done-face 'org-done) - (push txt ee))))) + (catch :skip + (org-agenda-skip) + (setq pos (1- (match-beginning 1)) + d2 (time-to-days + (org-time-string-to-time (match-string 1))) + diff (- d2 d1)) + ;; When to show a deadline in the calendar: + ;; If the expiration is within wdays warning time. + ;; Past-due deadlines are only shown on the current date + (if (and (< diff wdays) todayp (not (= diff 0))) + (save-excursion + (setq category (org-get-category)) + (if (re-search-backward "\\(^\\|\r\\)\\*+[ \t]*" nil t) + (progn + (goto-char (match-end 0)) + (setq pos1 (match-end 1)) + (setq tags (org-get-tags-at pos1)) + (setq head (buffer-substring-no-properties + (point) + (progn (skip-chars-forward "^\r\n") + (point)))) + (if (string-match org-looking-at-done-regexp head) + (setq txt nil) + (setq txt (org-format-agenda-item + (format "In %3d d.: " diff) head category tags)))) + (setq txt org-agenda-no-heading-message)) + (when txt + (setq face (cond ((<= diff 0) 'org-warning) + ((<= diff 5) 'org-upcoming-deadline) + (t nil))) + (org-add-props txt props + 'org-marker (org-agenda-new-marker pos) + 'org-hd-marker (org-agenda-new-marker pos1) + 'priority (+ (- 10 diff) (org-get-priority txt)) + 'category category + 'face face 'undone-face face 'done-face 'org-done) + (push txt ee)))))) ee)) (defun org-agenda-get-scheduled () @@ -7035,36 +7603,38 @@ the documentation of `org-diary'." ee txt head) (goto-char (point-min)) (while (re-search-forward regexp nil t) - (setq pos (1- (match-beginning 1)) - d2 (time-to-days - (org-time-string-to-time (match-string 1))) - diff (- d2 d1)) - ;; When to show a scheduled item in the calendar: - ;; If it is on or past the date. - (if (and (< diff 0) todayp) - (save-excursion - (setq category (org-get-category)) - (if (re-search-backward "\\(^\\|\r\\)\\*+[ \t]*" nil t) - (progn - (goto-char (match-end 0)) - (setq pos1 (match-end 1)) - (setq tags (org-get-tags-at)) - (setq head (buffer-substring-no-properties - (point) - (progn (skip-chars-forward "^\r\n") (point)))) - (if (string-match org-looking-at-done-regexp head) - (setq txt nil) - (setq txt (org-format-agenda-item - (format "Sched.%2dx: " (- 1 diff)) head - category tags)))) - (setq txt org-agenda-no-heading-message)) - (when txt - (org-add-props txt props - 'org-marker (org-agenda-new-marker pos) - 'org-hd-marker (org-agenda-new-marker pos1) - 'priority (+ (- 5 diff) (org-get-priority txt)) - 'category category) - (push txt ee))))) + (catch :skip + (org-agenda-skip) + (setq pos (1- (match-beginning 1)) + d2 (time-to-days + (org-time-string-to-time (match-string 1))) + diff (- d2 d1)) + ;; When to show a scheduled item in the calendar: + ;; If it is on or past the date. + (if (and (< diff 0) todayp) + (save-excursion + (setq category (org-get-category)) + (if (re-search-backward "\\(^\\|\r\\)\\*+[ \t]*" nil t) + (progn + (goto-char (match-end 0)) + (setq pos1 (match-end 1)) + (setq tags (org-get-tags-at)) + (setq head (buffer-substring-no-properties + (point) + (progn (skip-chars-forward "^\r\n") (point)))) + (if (string-match org-looking-at-done-regexp head) + (setq txt nil) + (setq txt (org-format-agenda-item + (format "Sched.%2dx: " (- 1 diff)) head + category tags)))) + (setq txt org-agenda-no-heading-message)) + (when txt + (org-add-props txt props + 'org-marker (org-agenda-new-marker pos) + 'org-hd-marker (org-agenda-new-marker pos1) + 'priority (+ (- 5 diff) (org-get-priority txt)) + 'category category) + (push txt ee)))))) ee)) (defun org-agenda-get-blocks () @@ -7081,34 +7651,36 @@ the documentation of `org-diary'." marker hdmarker ee txt d1 d2 s1 s2 timestr category tags) (goto-char (point-min)) (while (re-search-forward regexp nil t) - (setq timestr (match-string 0) - s1 (match-string 1) - s2 (match-string 2) - d1 (time-to-days (org-time-string-to-time s1)) - d2 (time-to-days (org-time-string-to-time s2))) - (if (and (> (- d0 d1) -1) (> (- d2 d0) -1)) - ;; Only allow days between the limits, because the normal - ;; date stamps will catch the limits. - (save-excursion - (setq marker (org-agenda-new-marker (point))) - (setq category (org-get-category)) - (if (re-search-backward "\\(^\\|\r\\)\\*+" nil t) - (progn - (setq hdmarker (org-agenda-new-marker (match-end 1))) - (goto-char (match-end 1)) - (setq tags (org-get-tags-at)) - (looking-at "\\*+[ \t]*\\([^\r\n]+\\)") - (setq txt (org-format-agenda-item - (format (if (= d1 d2) "" "(%d/%d): ") - (1+ (- d0 d1)) (1+ (- d2 d1))) - (match-string 1) category tags - (if (= d0 d1) timestr)))) - (setq txt org-agenda-no-heading-message)) - (org-add-props txt props - 'org-marker marker 'org-hd-marker hdmarker - 'priority (org-get-priority txt) 'category category) - (push txt ee))) - (outline-next-heading)) + (catch :skip + (org-agenda-skip) + (setq timestr (match-string 0) + s1 (match-string 1) + s2 (match-string 2) + d1 (time-to-days (org-time-string-to-time s1)) + d2 (time-to-days (org-time-string-to-time s2))) + (if (and (> (- d0 d1) -1) (> (- d2 d0) -1)) + ;; Only allow days between the limits, because the normal + ;; date stamps will catch the limits. + (save-excursion + (setq marker (org-agenda-new-marker (point))) + (setq category (org-get-category)) + (if (re-search-backward "\\(^\\|\r\\)\\*+" nil t) + (progn + (setq hdmarker (org-agenda-new-marker (match-end 1))) + (goto-char (match-end 1)) + (setq tags (org-get-tags-at)) + (looking-at "\\*+[ \t]*\\([^\r\n]+\\)") + (setq txt (org-format-agenda-item + (format (if (= d1 d2) "" "(%d/%d): ") + (1+ (- d0 d1)) (1+ (- d2 d1))) + (match-string 1) category tags + (if (= d0 d1) timestr)))) + (setq txt org-agenda-no-heading-message)) + (org-add-props txt props + 'org-marker marker 'org-hd-marker hdmarker + 'priority (org-get-priority txt) 'category category) + (push txt ee))) + (outline-next-heading))) ;; Sort the entries by expiration date. (nreverse ee))) @@ -7709,9 +8281,7 @@ be used to request time specification in the time stamp." (org-agenda-check-no-diary) (let* ((marker (or (get-text-property (point) 'org-marker) (org-agenda-error))) - (buffer (marker-buffer marker)) - (pos (marker-position marker)) - (hdmarker (get-text-property (point) 'org-hd-marker))) + (pos (marker-position marker))) (with-current-buffer (marker-buffer marker) (widen) (goto-char pos) @@ -7877,53 +8447,59 @@ are included in the output." lspos tags tags-list tags-alist (llast 0) rtn level category i txt todo marker) - (save-excursion (goto-char (point-min)) (when (eq action 'sparse-tree) (org-overview)) (while (re-search-forward re nil t) - (setq todo (if (match-end 1) (match-string 2)) - tags (if (match-end 4) (match-string 4))) - (goto-char (setq lspos (1+ (match-beginning 0)))) - (setq level (funcall outline-level) - category (org-get-category)) - (setq i llast llast level) - ;; remove tag lists from same and sublevels - (while (>= i level) - (when (setq entry (assoc i tags-alist)) - (setq tags-alist (delete entry tags-alist))) - (setq i (1- i))) - ;; add the nex tags - (when tags - (setq tags (mapcar 'downcase (org-split-string tags ":")) - tags-alist - (cons (cons level tags) tags-alist))) - ;; compile tags for current headline - (setq tags-list - (if org-use-tag-inheritance - (apply 'append (mapcar 'cdr tags-alist)) - tags)) - (when (and (or (not todo-only) todo) - (eval matcher)) - ;; list this headline - (if (eq action 'sparse-tree) - (progn - (org-show-hierarchy-above)) - (setq txt (org-format-agenda-item - "" - (concat - (if org-tags-match-list-sublevels - (make-string (1- level) ?.) "") - (org-get-heading)) - category tags-list)) - (goto-char lspos) - (setq marker (org-agenda-new-marker)) - (org-add-props txt props - 'org-marker marker 'org-hd-marker marker 'category category) - (push txt rtn)) - ;; if we are to skip sublevels, jump to end of subtree - (point) - (or org-tags-match-list-sublevels (org-end-of-subtree))))) + (catch :skip + (and (eq action 'agenda) (org-agenda-skip)) + (setq todo (if (match-end 1) (match-string 2)) + tags (if (match-end 4) (match-string 4))) + (goto-char (setq lspos (1+ (match-beginning 0)))) + (setq level (funcall outline-level) + category (org-get-category)) + (setq i llast llast level) + ;; remove tag lists from same and sublevels + (while (>= i level) + (when (setq entry (assoc i tags-alist)) + (setq tags-alist (delete entry tags-alist))) + (setq i (1- i))) + ;; add the nex tags + (when tags + (setq tags (mapcar 'downcase (org-split-string tags ":")) + tags-alist + (cons (cons level tags) tags-alist))) + ;; compile tags for current headline + (setq tags-list + (if org-use-tag-inheritance + (apply 'append (mapcar 'cdr tags-alist)) + tags)) + (when (and (or (not todo-only) todo) + (eval matcher) + (or (not org-agenda-skip-archived-trees) + (not (member org-archive-tag tags-list)))) + ;; list this headline + (if (eq action 'sparse-tree) + (progn + (org-show-hierarchy-above)) + (setq txt (org-format-agenda-item + "" + (concat + (if org-tags-match-list-sublevels + (make-string (1- level) ?.) "") + (org-get-heading)) + category tags-list)) + (goto-char lspos) + (setq marker (org-agenda-new-marker)) + (org-add-props txt props + 'org-marker marker 'org-hd-marker marker 'category category) + (push txt rtn)) + ;; if we are to skip sublevels, jump to end of subtree + (point) + (or org-tags-match-list-sublevels (org-end-of-subtree)))))) + (when (and (eq action 'sparse-tree) + (not org-sparse-tree-open-archived-trees)) + (org-hide-archived-subtrees (point-min) (point-max))) (nreverse rtn))) (defun org-tags-sparse-tree (&optional arg match) @@ -7994,6 +8570,7 @@ The prefix arg TODO-ONLY limits the search to TODO entries." (list 'if 'current-prefix-arg nil match) t)) (setq files (org-agenda-files) rtnall nil) + (org-prepare-agenda-buffers files) (while (setq file (pop files)) (catch 'nextfile (org-check-agenda-file file) @@ -8084,7 +8661,11 @@ 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 "" " "))) - (unless (equal tags "") + (if (equal tags "") + (save-excursion + (beginning-of-line 1) + (and (re-search-forward "[ \t]+$" (point-at-eol) t) + (replace-match ""))) (move-to-column (max (current-column) (if (> org-tags-column 0) org-tags-column @@ -8590,7 +9171,7 @@ in all files." (defun org-search-not-link (&rest args) "Execute `re-search-forward', but only accept matches that are not a link." (catch 'exit - (let ((pos (point)) p1) + (let (p1) (while (apply 're-search-forward args) (setq p1 (point)) (if (not (save-match-data @@ -8990,24 +9571,23 @@ If the file does not exist, an error is thrown." (setq in-emacs (or in-emacs line search)) (let* ((file (if (equal path "") buffer-file-name - (convert-standard-filename (org-expand-file-name path)))) - (dirp (file-directory-p file)) + path)) + (apps (append org-file-apps (org-default-apps))) + (remp (and (assq 'remote apps) (org-file-remote-p file))) + (dirp (if remp nil (file-directory-p file))) (dfile (downcase file)) (old-buffer (current-buffer)) (old-pos (point)) (old-mode major-mode) - ext cmd apps) - (if (and (not (file-exists-p file)) - (not org-open-non-existing-files)) - (error "No such file: %s" file)) + ext cmd) (if (string-match "^.*\\.\\([a-zA-Z0-9]+\\.gz\\)$" dfile) (setq ext (match-string 1 dfile)) (if (string-match "^.*\\.\\([a-zA-Z0-9]+\\)$" dfile) (setq ext (match-string 1 dfile)))) - (setq apps (append org-file-apps (org-default-apps))) (if in-emacs (setq cmd 'emacs) - (setq cmd (or (and dirp (cdr (assoc 'directory apps))) + (setq cmd (or (and remp (cdr (assoc 'remote apps))) + (and dirp (cdr (assoc 'directory apps))) (cdr (assoc ext apps)) (cdr (assoc t apps))))) (when (eq cmd 'mailcap) @@ -9018,6 +9598,10 @@ If the file does not exist, an error is thrown." (if (stringp command) (setq cmd command) (setq cmd 'emacs)))) + (if (and (not (eq cmd 'emacs)) ; Emacs has not problems with non-ex files + (not (file-exists-p file)) + (not org-open-non-existing-files)) + (error "No such file: %s" file)) (cond ((and (stringp cmd) (not (string-match "^\\s-*$" cmd))) ;; Normalize use of quote, this can vary. @@ -9028,8 +9612,9 @@ If the file does not exist, an error is thrown." (shell-command (concat cmd " &")))) ((or (stringp cmd) (eq cmd 'emacs)) - (unless (equal (file-truename file) (file-truename (or buffer-file-name ""))) - (funcall (cdr (assq 'file org-link-frame-setup)) file)) +; (unless (equal (file-truename file) (file-truename (or buffer-file-name ""))) +; (funcall (cdr (assq 'file org-link-frame-setup)) file)) + (funcall (cdr (assq 'file org-link-frame-setup)) file) (if line (goto-line line) (if search (org-link-search search)))) ((consp cmd) @@ -9053,6 +9638,20 @@ If the file does not exist, an error is thrown." "Replace special path abbreviations and expand the file name." (expand-file-name path)) +(defun org-file-remote-p (file) + "Test whether FILE specifies a location on a remote system. +Return non-nil if the location is indeed remote. + +For example, the filename \"/user@host:/foo\" specifies a location +on the system \"/user@host:\"." + (cond ((fboundp 'file-remote-p) + (file-remote-p file)) + ((fboundp 'tramp-handle-file-remote-p) + (tramp-handle-file-remote-p file)) + ((and (boundp 'ange-ftp-name-format) + (string-match ange-ftp-name-format file)) + t) + (t nil))) (defvar org-insert-link-history nil "Minibuffer history for links inserted with `org-insert-link'.") @@ -9186,8 +9785,8 @@ For file links, arg negates `org-context-in-file-links'." (setq cpltxt (url-view-url t) link (org-make-link cpltxt))) ((eq major-mode 'w3m-mode) - (setq cpltxt w3m-current-url - link (org-make-link cpltxt))) + (setq cpltxt (or w3m-current-title w3m-current-url) + link (org-make-link w3m-current-url))) ((setq search (run-hook-with-args-until-success 'org-create-file-search-functions)) @@ -9195,6 +9794,11 @@ For file links, arg negates `org-context-in-file-links'." "::" search)) (setq cpltxt (or description link))) + ((eq major-mode 'image-mode) + (setq cpltxt (concat "file:" + (abbreviate-file-name buffer-file-name)) + link (org-make-link cpltxt))) + ((eq major-mode 'org-mode) ;; Just link to current headline (setq cpltxt (concat "file:" @@ -9414,7 +10018,9 @@ subdirectory. Otherwise, the link will be the absolute path as completed in the minibuffer (i.e. normally ~/path/to/file). With two \\[universal-argument] prefixes, enforce an absolute path even if the file -is in the current directory or below." +is in the current directory or below. +With three \\[universal-argument] prefixes, negate the meaning of +`org-keep-stored-link-after-insertion'." (interactive "P") (let (link desc entry remove file (pos (point))) (cond @@ -9430,7 +10036,7 @@ is in the current directory or below." (setq link (read-string "Link: " (org-link-unescape (org-match-string-no-properties 1))))) - (complete-file + ((equal complete-file '(4)) ;; Completing read for file names. (setq file (read-file-name "File: ")) (let ((pwd (file-name-as-directory (expand-file-name "."))) @@ -9455,7 +10061,8 @@ is in the current directory or below." org-insert-link-history (or (car (car org-stored-links))))) (setq entry (assoc link org-stored-links)) - (if (not org-keep-stored-link-after-insertion) + (if (funcall (if (equal complete-file '(64)) 'not 'identity) + (not org-keep-stored-link-after-insertion)) (setq org-stored-links (delq (assoc link org-stored-links) org-stored-links))) (setq link (if entry (nth 1 entry) link) @@ -9908,7 +10515,7 @@ This is being used to correctly align a single field after TAB or RET.") (linepos (+ (if (bolp) 1 0) (count-lines (point-min) (point)))) (colpos (org-table-current-column)) (winstart (window-start)) - text lines (new "") lengths l typenums ty fields maxfields i + lines (new "") lengths l typenums ty fields maxfields i column (indent "") cnt frac rfmt hfmt @@ -9919,7 +10526,7 @@ This is being used to correctly align a single field after TAB or RET.") (make-string sp2 ?\ ) "%%%s%ds" (make-string sp1 ?\ ) "|")) (hfmt1 (concat (make-string sp2 ?-) "%s" (make-string sp1 ?-) "+")) - emptystrings xx links narrow fmax fmin f1 len c e) + emptystrings links narrow fmax f1 len c e) (untabify beg end) (remove-text-properties beg end '(org-cwidth t display t)) ;; Check if we have links @@ -11477,10 +12084,10 @@ not overwrite the stored one." ;; Insert ranges in current column (while (string-match "\\&[-I0-9]+" form) (setq form (replace-match - (save-match-data - (org-table-get-vertical-vector (match-string 0 form) - nil n0)) - t t form))) + (save-match-data + (org-table-get-vertical-vector (match-string 0 form) + nil n0)) + t t form))) (if lispp (setq ev (eval (eval (read form))) ev (if (numberp ev) (number-to-string ev) ev)) @@ -12055,9 +12662,11 @@ overwritten, and the table is not marked as requiring realignment." (:headline-levels . org-export-headline-levels) (:section-numbers . org-export-with-section-numbers) (:table-of-contents . org-export-with-toc) + (:archived-trees . org-export-with-archived-trees) (:emphasize . org-export-with-emphasize) (:sub-superscript . org-export-with-sub-superscripts) (:TeX-macros . org-export-with-TeX-macros) + (:LaTeX-fragments . org-export-with-LaTeX-fragments) (:fixed-width . org-export-with-fixed-width) (:timestamps . org-export-with-timestamps) (:tables . org-export-with-tables) @@ -12088,7 +12697,6 @@ overwritten, and the table is not marked as requiring realignment." (goto-char 0) (let ((re (org-make-options-regexp '("TITLE" "AUTHOR" "EMAIL" "TEXT" "OPTIONS" "LANGUAGE"))) - (text nil) p key val text options) (while (re-search-forward re nil t) (setq key (org-match-string-no-properties 1) @@ -12112,7 +12720,8 @@ overwritten, and the table is not marked as requiring realignment." ("|" . :tables) ("^" . :sub-superscript) ("*" . :emphasize) - ("TeX" . :TeX-macros))) + ("TeX" . :TeX-macros) + ("LaTeX" . :LaTeX-fragments))) o) (while (setq o (pop op)) (if (string-match (concat (regexp-quote (car o)) @@ -12199,7 +12808,8 @@ ones and overrule settings in the other lists." \[X] publish... (project will be prompted for) \[A] publish all projects") (cmds - '((?v . org-export-visible) + '((?t . org-insert-export-options-template) + (?v . org-export-visible) (?a . org-export-as-ascii) (?h . org-export-as-html) (?b . org-export-as-html-and-open) @@ -12526,32 +13136,56 @@ translations. There is currently no way for users to extend this.") (defun org-cleaned-string-for-export (string &rest parameters) "Cleanup a buffer substring so that links can be created safely." (interactive) - (let* ((cb (current-buffer)) - (re-radio (and org-target-link-regexp + (let* ((re-radio (and org-target-link-regexp (concat "\\([^<]\\)\\(" org-target-link-regexp "\\)"))) (re-plain-link (concat "\\([^[<]\\)" org-plain-link-re)) (re-angle-link (concat "\\([^[]\\)" org-angle-link-re)) + (re-archive (concat ":" org-archive-tag ":")) rtn) (save-excursion (set-buffer (get-buffer-create " org-mode-tmp")) (erase-buffer) (insert string) - (org-mode) + (let ((org-inhibit-startup t)) (org-mode)) + + ;; Get rid of archived trees + (when (not (eq org-export-with-archived-trees t)) + (goto-char (point-min)) + (while (re-search-forward re-archive nil t) + (if (not (org-on-heading-p)) + (org-end-of-subtree t) + (beginning-of-line 1) + (delete-region + (if org-export-with-archived-trees (1+ (point-at-eol)) (point)) + (org-end-of-subtree))))) + ;; Find targets in comments and move them out of comments, ;; but mark them as targets that should be invisible (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 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 \\3") (goto-char (match-beginning 0))) + + ;; Convert LaTeX fragments to images + (when (memq :LaTeX-fragments parameters) + (org-format-latex + (concat "ltxpng/" (file-name-sans-extension + (file-name-nondirectory + org-current-export-file))) + org-current-export-dir nil "Creating LaTeX image %s")) + (message "Exporting...") + ;; Normalize links: Convert angle and plain links into bracket links (goto-char (point-min)) (while (re-search-forward re-plain-link nil t) @@ -12565,8 +13199,9 @@ translations. There is currently no way for users to extend this.") (concat (match-string 1) "[[" (match-string 2) ":" (match-string 3) "]]") t t)) + ;; Find multiline emphasis and put them into single line - (when (assq :emph-multiline parameters) + (when (memq :emph-multiline parameters) (goto-char (point-min)) (while (re-search-forward org-emph-re nil t) (subst-char-in-region (match-beginning 0) (match-end 0) ?\n ?\ t) @@ -12671,7 +13306,6 @@ underlined headlines. The default is 3." (title (or (plist-get opt-plist :title) (file-name-sans-extension (file-name-nondirectory buffer-file-name)))) - (options nil) (email (plist-get opt-plist :email)) (language (plist-get opt-plist :language)) (text nil) @@ -12772,7 +13406,7 @@ underlined headlines. The default is 3." (normal-mode) (save-buffer) ;; remove display and invisible chars - (let (beg end s) + (let (beg end) (goto-char (point-min)) (while (setq beg (next-single-property-change (point) 'display)) (setq end (next-single-property-change beg 'display)) @@ -12849,22 +13483,27 @@ underlined headlines. The default is 3." (defun org-export-visible (type arg) "Create a copy of the visible part of the current buffer, and export it. The copy is created in a temporary buffer and removed after use. -TYPE is the final key (as a string) of the `C-c C-x' key sequence that will -run the export command - in interactive use, the command prompts for this -key. As a special case, if the you type SPC at the prompt, the temporary +TYPE is the final key (as a string) that also select the export command in +the `C-c C-e' export dispatcher. +As a special case, if the you type SPC at the prompt, the temporary org-mode file will not be removed but presented to you so that you can continue to use it. The prefix arg ARG is passed through to the exporting command." (interactive (list (progn (message "Export visible: [a]SCII [h]tml [b]rowse HTML [x]OXO [ ]keep buffer") - (char-to-string (read-char-exclusive))) + (read-char-exclusive)) current-prefix-arg)) - (if (not (member type '("a" "\C-a" "b" "\C-b" "h" "x" " "))) + (if (not (member type '(?a ?\C-a ?b ?\C-b ?h ?x ?\ ))) (error "Invalid export key")) - ;; FIXME: do this more explicit? - (let* ((binding (key-binding (concat "\C-c\C-x" type))) - (keepp (equal type " ")) + (let* ((binding (cdr (assoc type + '((?a . org-export-as-ascii) + (?\C-a . org-export-as-ascii) + (?b . org-export-as-html-and-open) + (?\C-b . org-export-as-html-and-open) + (?h . org-export-as-html) + (?x . org-export-as-xoxo))))) + (keepp (equal type ?\ )) (file buffer-file-name) (buffer (get-buffer-create "*Org Export Visible*")) s e) @@ -12925,7 +13564,7 @@ Does include HTML export options as well as TODO and CATEGORY stuff." #+EMAIL: %s #+LANGUAGE: %s #+TEXT: Some descriptive text to be emitted. Several lines OK. -#+OPTIONS: H:%d num:%s toc:%s \\n:%s @:%s ::%s |:%s ^:%s *:%s TeX:%s +#+OPTIONS: H:%d num:%s toc:%s \\n:%s @:%s ::%s |:%s ^:%s *:%s TeX:%s LaTeX:%s #+CATEGORY: %s #+SEQ_TODO: %s #+TYP_TODO: %s @@ -12944,6 +13583,7 @@ Does include HTML export options as well as TODO and CATEGORY stuff." org-export-with-sub-superscripts org-export-with-emphasize org-export-with-TeX-macros + org-export-with-LaTeX-fragments (file-name-nondirectory buffer-file-name) (if (equal org-todo-interpretation 'sequence) (mapconcat 'identity org-todo-keywords " ") @@ -13041,6 +13681,7 @@ When HIDDEN is non-nil, don't display the HTML buffer. EXT-PLIST is a property list with external parameters overriding org-mode's default settings, but still inferior to file-local settings." (interactive "P") + (message "Exporting...") (setq-default org-todo-line-regexp org-todo-line-regexp) (setq-default org-deadline-line-regexp org-deadline-line-regexp) (setq-default org-done-string org-done-string) @@ -13049,16 +13690,24 @@ org-mode's default settings, but still inferior to file-local settings." (org-infile-export-plist))) (style (plist-get opt-plist :style)) + (link-validate (plist-get opt-plist :link-validation-function)) + valid (odd org-odd-levels-only) (region-p (org-region-active-p)) (region (buffer-substring (if region-p (region-beginning) (point-min)) (if region-p (region-end) (point-max)))) + ;; The following two are dynamically scoped into other + ;; routines below. + (org-current-export-dir (org-export-directory :html opt-plist)) + (org-current-export-file buffer-file-name) (all_lines (org-skip-comments (org-split-string (org-cleaned-string-for-export - region :emph-multiline) + region :emph-multiline + (if (plist-get opt-plist :LaTeX-fragments) + :LaTeX-fragments)) "[\r\n]"))) (lines (org-export-find-first-heading-line all_lines)) (level 0) (line "") (origline "") txt todo @@ -13068,6 +13717,7 @@ org-mode's default settings, but still inferior to file-local settings." (file-name-sans-extension (file-name-nondirectory buffer-file-name)) ".html")) + (current-dir (file-name-directory buffer-file-name)) (buffer (find-file-noselect filename)) (levels-open (make-vector org-level-max nil)) (date (format-time-string "%Y/%m/%d" (current-time))) @@ -13314,6 +13964,10 @@ lang=\"%s\" xml:lang=\"%s\"> (if (string-match "::\\(.*\\)" filename) (setq search (match-string 1 filename) filename (replace-match "" t nil filename))) + (setq valid + (if (functionp link-validate) + (funcall link-validate filename current-dir) + t)) (setq file-is-image-p (string-match (org-image-file-name-regexp) filename)) (setq thefile (if abs-p (expand-file-name filename) filename)) @@ -13339,7 +13993,8 @@ lang=\"%s\" xml:lang=\"%s\"> (and org-export-html-inline-images (not descp)))) (concat "<img src=\"" thefile "\"/>") - (concat "<a href=\"" thefile "\">" desc "</a>"))))) + (concat "<a href=\"" thefile "\">" desc "</a>"))) + (if (not valid) (setq rpl desc)))) ((member type '("bbdb" "vm" "wl" "mhe" "rmail" "gnus" "shell" "info" "elisp")) (setq rpl (concat "<i><" type ":" (save-match-data (org-link-unescape path)) @@ -13497,7 +14152,9 @@ lang=\"%s\" xml:lang=\"%s\"> (while (re-search-forward "<li>[ \r\n\t]*</li>\n?" nil t) (replace-match "")) (save-buffer) - (goto-char (point-min))))) + (goto-char (point-min)) + (message "Exporting... done")))) + (defun org-format-table-html (lines olines) "Find out which HTML converter to use and return the HTML code." @@ -13650,27 +14307,31 @@ But it has the disadvantage, that Org-mode's HTML conversions cannot be used." (defun org-html-handle-time-stamps (s) "Format time stamps in string S, or remove them." - (let (r b) - (while (string-match org-maybe-keyword-time-regexp s) - (or b (setq b (substring s 0 (match-beginning 0)))) - (if (not org-export-with-timestamps) - (setq r (concat r (substring s 0 (match-beginning 0))) - s (substring s (match-end 0))) - (setq r (concat - r (substring s 0 (match-beginning 0)) - (if (match-end 1) - (format "@<span class=\"timestamp-kwd\">%s @</span>" - (match-string 1 s))) - (format " @<span class=\"timestamp\">%s@</span>" - (substring (match-string 3 s) 1 -1))) - s (substring s (match-end 0))))) - ;; Line break of line started and ended with time stamp stuff - (if (not r) - s - (setq r (concat r s)) - (unless (string-match "\\S-" (concat b s)) - (setq r (concat r "@<br/>"))) - r))) + (catch 'exit + (let (r b) + (while (string-match org-maybe-keyword-time-regexp s) + ;; FIXME: is it good to never export CLOCK, or do we need control? + (if (and (match-end 1) (equal (match-string 1 s) org-clock-string)) + (throw 'exit "")) + (or b (setq b (substring s 0 (match-beginning 0)))) + (if (not org-export-with-timestamps) + (setq r (concat r (substring s 0 (match-beginning 0))) + s (substring s (match-end 0))) + (setq r (concat + r (substring s 0 (match-beginning 0)) + (if (match-end 1) + (format "@<span class=\"timestamp-kwd\">%s @</span>" + (match-string 1 s))) + (format " @<span class=\"timestamp\">%s@</span>" + (substring (match-string 3 s) 1 -1))) + s (substring s (match-end 0))))) + ;; Line break if line started and ended with time stamp stuff + (if (not r) + s + (setq r (concat r s)) + (unless (string-match "\\S-" (concat b s)) + (setq r (concat r "@<br/>"))) + r)))) (defun org-html-protect (s) ;; convert & to &, < to < and > to > @@ -14147,6 +14808,293 @@ a time), or the day by one (if it does not contain a time)." (setq fmt (if have-time ":%Y%m%dT%H%M%S" ";VALUE=DATE:%Y%m%d")) (concat keyword (format-time-string fmt time)))) +;;; LaTeX stuff + +(defvar org-cdlatex-mode-map (make-sparse-keymap) + "Keymap for the minor `org-cdlatex-mode'.") + +(define-key org-cdlatex-mode-map "_" 'org-cdlatex-underscore-caret) +(define-key org-cdlatex-mode-map "^" 'org-cdlatex-underscore-caret) +(define-key org-cdlatex-mode-map "`" 'cdlatex-math-symbol) +(define-key org-cdlatex-mode-map "'" 'org-cdlatex-math-modify) +(define-key org-cdlatex-mode-map "\C-c{" 'cdlatex-environment) + +(defvar org-cdlatex-texmathp-advice-is-done nil + "Flag remembering if we have applied the advice to texmathp already.") + +(define-minor-mode org-cdlatex-mode + "Toggle the minor `org-cdlatex-mode'. +This mode supports entering LaTeX environment and math in LaTeX fragments +in Org-mode. +\\{org-cdlatex-mode-map}" + nil " OCDL" nil + (when org-cdlatex-mode (require 'cdlatex)) + (unless org-cdlatex-texmathp-advice-is-done + (setq org-cdlatex-texmathp-advice-is-done t) + (defadvice texmathp (around org-math-always-on activate) + "Always return t in org-mode buffers. +This is because we want to insert math symbols without dollars even outside +the LaTeX math segments. If Orgmode thinks that point is actually inside +en embedded LaTeX fragement, let texmathp do its job. +\\[org-cdlatex-mode-map]" + (interactive) + (let (p) + (cond + ((not (eq major-mode 'org-mode)) ad-do-it) + ((eq this-command 'cdlatex-math-symbol) + (setq ad-return-value t + texmathp-why '("cdlatex-math-symbol in org-mode" . 0))) + (t + (let ((p (org-inside-LaTeX-fragment-p))) + (if (and p (member (car p) (plist-get org-format-latex-options :matchers))) + (setq ad-return-value t + texmathp-why '("Org-mode embedded math" . 0)) + (if p ad-do-it))))))))) + +(defun turn-on-org-cdlatex () + "Unconditionally turn on `org-cdlatex-mode'." + (org-cdlatex-mode 1)) + +(defun org-inside-LaTeX-fragment-p () + "Test if point is inside a LaTeX fragment. +I.e. after a \\begin, \\(, \\[, $, or $$, without the corresponding closing +sequence appearing also before point. +Even though the matchers for math are configurable, this function assumes +that \\begin, \\(, \\[, and $$ are always used. Only the single dollar +delimiters are skipped when they have been removed by customization. +The return value is nil, or a cons cell with the delimiter and +and the position of this delimiter. + +This function does a reasonably good job, but can locally be fooled by +for example currency specifications. For example it will assume being in +inline math after \"$22.34\". The LaTeX fragment formatter will only format +fragments that are properly closed, but during editing, we have to live +with the uncertainty caused by missing closing delimiters. This function +looks only before point, not after." + (catch 'exit + (let ((pos (point)) + (dodollar (member "$" (plist-get org-format-latex-options :matchers))) + (lim (progn + (re-search-backward (concat "^\\(" paragraph-start "\\)") nil t) + (point))) + dd-on str (start 0) m re) + (goto-char pos) + (when dodollar + (setq str (concat (buffer-substring lim (point)) "\000 X$.") + re (nth 1 (assoc "$" org-latex-regexps))) + (while (string-match re str start) + (cond + ((= (match-end 0) (length str)) + (throw 'exit (cons "$" (+ lim (match-beginning 0))))) + ((= (match-end 0) (- (length str) 5)) + (throw 'exit nil)) + (t (setq start (match-end 0)))))) + (when (setq m (re-search-backward "\\(\\\\begin{[^}]*}\\|\\\\(\\|\\\\\\[\\)\\|\\(\\\\end{[^}]*}\\|\\\\)\\|\\\\\\]\\)\\|\\(\\$\\$\\)" lim t)) + (goto-char pos) + (and (match-beginning 1) (throw 'exit (cons (match-string 1) m))) + (and (match-beginning 2) (throw 'exit nil)) + ;; count $$ + (while (re-search-backward "\\$\\$" lim t) + (setq dd-on (not dd-on))) + (goto-char pos) + (if dd-on (cons "$$" m)))))) + + +(defun org-try-cdlatex-tab () + "Check if it makes sense to execute `cdlatex-tab', and do it if yes. +It makes sense to do so if `org-cdlatex-mode' is active and if the cursor is + - inside a LaTeX fragment, or + - after the first word in a line, where an abbreviation expansion could + insert a LaTeX environment." + ;; FIXME: This may still need refinement. + (when org-cdlatex-mode + (cond + ((save-excursion + (skip-chars-backward "a-zA-Z0-9*") + (skip-chars-backward " \t") + (bolp)) + (cdlatex-tab) t) + ((org-inside-LaTeX-fragment-p) + (cdlatex-tab) t) + (t nil)))) + +(defun org-cdlatex-underscore-caret (&optional arg) + "Execute `cdlatex-sub-superscript' in LaTeX fragments. +Revert to the normal definition outside of these fragments." + (interactive "P") + (if (org-inside-LaTeX-fragment-p) + (call-interactively 'cdlatex-sub-superscript) + (let (org-cdlatex-mode) + (call-interactively (key-binding (vector last-input-event)))))) + +(defun org-cdlatex-math-modify (&optional arg) + "Execute `cdlatex-math-modify' in LaTeX fragments. +Revert to the normal definition outside of these fragments." + (interactive "P") + (if (org-inside-LaTeX-fragment-p) + (call-interactively 'cdlatex-math-modify) + (let (org-cdlatex-mode) + (call-interactively (key-binding (vector last-input-event)))))) + +(defvar org-latex-fragment-image-overlays nil + "List of overlays carrying the images of latex fragments.") +(make-variable-buffer-local 'org-latex-fragment-image-overlays) + +(defun org-remove-latex-fragment-image-overlays () + "Remove all overlays with LaTeX fragment images in current buffer." + (mapc 'org-delete-overlay org-latex-fragment-image-overlays) + (setq org-latex-fragment-image-overlays nil)) + +(defun org-preview-latex-fragment (&optional subtree) + "Preview the LaTeX fragment at point, or all locally or globally. +If the cursor is in a LaTeX fragment, create the image and overlay +it over the source code. If there is no fragment at point, display +all fragments in the current text, from one headline to the next. With +prefix SUBTREE, display all fragments in the current subtree. With a +double prefix `C-u C-u', or when the cursor is before the first headline, +display all fragments in the buffer. +The images can be removed again with \\[org-ctrl-c-ctrl-c]." + (interactive "P") + (org-remove-latex-fragment-image-overlays) + (save-excursion + (save-restriction + (let (beg end at msg) + (cond + ((or (equal subtree '(16)) + (not (save-excursion + (re-search-backward (concat "^" outline-regexp) nil t)))) + (setq beg (point-min) end (point-max) + msg "Creating images for buffer...%s")) + ((equal subtree '(4)) + (org-back-to-heading) + (setq beg (point) end (org-end-of-subtree) + msg "Creating images for subtree...%s")) + (t + (if (setq at (org-inside-LaTeX-fragment-p)) + (goto-char (max (point-min) (- (cdr at) 2))) + (org-back-to-heading)) + (setq beg (point) end (progn (outline-next-heading) (point)) + msg (if at "Creating image...%s" + "Creating images for entry...%s")))) + (message msg "") + (narrow-to-region beg end) + (org-format-latex + (concat "ltxpng/" (file-name-sans-extension + (file-name-nondirectory + buffer-file-name))) + default-directory 'overlays msg at) + (message msg "done. Use `C-c C-c' to remove images."))))) + +(defvar org-latex-regexps + '(("begin" "^[ \t]*\\(\\\\begin{\\([a-zA-Z0-9\\*]+\\)[^\000]+?\\\\end{\\2}\\)" 1 t) + ;; ("$" "\\([ (]\\|^\\)\\(\\(\\([$]\\)\\([^ \r\n,.$].*?\\(\n.*?\\)\\{0,5\\}[^ \r\n,.$]\\)\\4\\)\\)\\([ .,?;:'\")]\\|$\\)" 2 nil) + ;; \000 in the following regex is needed for org-inside-LaTeX-fragment-p + ("$" "\\([^$]\\)\\(\\(\\$\\([^ \r\n,;.$][^$\n\r]*?\\(\n[^$\n\r]*?\\)\\{0,2\\}[^ \r\n,.$]\\)\\$\\)\\)\\([ .,?;:'\")\000]\\|$\\)" 2 nil) + ("\\(" "\\\\([^\000]*?\\\\)" 0 nil) + ("\\[" "\\\\\\[[^\000]*?\\\\\\]" 0 t) + ("$$" "\\$\\$[^\000]*?\\$\\$" 0 t)) + "Regular expressions for matching embedded LaTeX.") + +(defun org-format-latex (prefix &optional dir overlays msg at) + "Replace LaTeX fragments with links to an image, and produce images." + (if (and overlays (fboundp 'clear-image-cache)) (clear-image-cache)) + (let* ((prefixnodir (file-name-nondirectory prefix)) + (absprefix (expand-file-name prefix dir)) + (todir (file-name-directory absprefix)) + (opt org-format-latex-options) + (matchers (plist-get opt :matchers)) + (re-list org-latex-regexps) + (cnt 0) txt link beg end re e oldfiles + m n block linkfile movefile ov) + ;; Make sure the directory exists + (or (file-directory-p todir) (make-directory todir)) + ;; Check if there are old images files with this prefix, and remove them + (setq oldfiles (directory-files + todir 'full + (concat (regexp-quote prefixnodir) "_[0-9]+\\.png$"))) + (while oldfiles (delete-file (pop oldfiles))) + ;; Check the different regular expressions + (while (setq e (pop re-list)) + (setq m (car e) re (nth 1 e) n (nth 2 e) + block (if (nth 3 e) "\n\n" "")) + (when (member m matchers) + (goto-char (point-min)) + (while (re-search-forward re nil t) + (when (or (not at) (equal (cdr at) (match-beginning n))) + (setq txt (match-string n) + beg (match-beginning n) end (match-end n) + cnt (1+ cnt) + linkfile (format "%s_%04d.png" prefix cnt) + movefile (format "%s_%04d.png" absprefix cnt) + link (concat block "[[file:" linkfile "]]" block)) + (if msg (message msg cnt)) + (goto-char beg) + (org-create-formula-image + txt movefile opt) + (if overlays + (progn + (setq ov (org-make-overlay beg end)) + (if (featurep 'xemacs) + (progn + (org-overlay-put ov 'invisible t) + (org-overlay-put + ov 'end-glyph + (make-glyph (vector 'png :file movefile)))) + (org-overlay-put + ov 'display + (list 'image :type 'png :file movefile :ascent 'center))) + (push ov org-latex-fragment-image-overlays) + (goto-char end)) + (delete-region beg end) + (insert link)))))))) + +;; This function borrows from Ganesh Swami's latex2png.el +(defun org-create-formula-image (string tofile options) + (let* ((tmpdir (if (featurep 'xemacs) + (temp-directory) + temporary-file-directory)) + (texfilebase (make-temp-name + (expand-file-name "orgtex" tmpdir))) + +;(texfilebase (make-temp-file "orgtex")) +; (dummy (delete-file texfilebase)) + (texfile (concat texfilebase ".tex")) + (dvifile (concat texfilebase ".dvi")) + (pngfile (concat texfilebase ".png")) + (scale (number-to-string (* 1000 (or (plist-get options :scale) 1.0)))) + (fg (or (plist-get options :foreground) "Black")) + (bg (or (plist-get options :background) "Transparent"))) + (with-temp-file texfile + (insert "\\documentclass{article} +\\usepackage{fullpage} +\\usepackage{amssymb} +\\usepackage[usenames]{color} +\\usepackage{amsmath} +\\usepackage{latexsym} +\\usepackage[mathscr]{eucal} +\\pagestyle{empty} +\\begin{document}\n" string "\n\\end{document}\n")) + (let ((dir default-directory)) + (condition-case nil + (progn + (cd tmpdir) + (call-process "latex" nil nil nil texfile)) + (error nil)) + (cd dir)) + (if (not (file-exists-p dvifile)) + (progn (message "Failed to create dvi file from %s" texfile) nil) + (call-process "dvipng" nil nil nil + "-E" "-fg" fg "-bg" bg + "-x" scale "-y" scale "-T" "tight" + "-o" pngfile + dvifile) + (if (not (file-exists-p pngfile)) + (progn (message "Failed to create png file from %s" texfile) nil) + ;; Use the requested file name and clean up + (copy-file pngfile tofile 'replace) + (loop for e in '(".dvi" ".tex" ".aux" ".log" ".png") do + (delete-file (concat texfilebase e))) + pngfile)))) ;;; Key bindings @@ -14212,7 +15160,9 @@ a time), or the day by one (if it does not contain a time)." ;; All the other keys (define-key org-mode-map "\C-c\C-a" 'show-all) ; in case allout messed up. +(define-key org-mode-map "\C-xns" 'org-narrow-to-subtree) (define-key org-mode-map "\C-c$" 'org-archive-subtree) +(define-key org-mode-map "\C-c\C-x\C-a" 'org-toggle-archive-tag) (define-key org-mode-map "\C-c\C-j" 'org-goto) (define-key org-mode-map "\C-c\C-t" 'org-todo) (define-key org-mode-map "\C-c\C-s" 'org-schedule) @@ -14255,24 +15205,7 @@ a time), or the day by one (if it does not contain a time)." (define-key org-mode-map "\C-c~" 'org-table-create-with-table.el) (define-key org-mode-map "\C-c\C-q" 'org-table-wrap-region) (define-key org-mode-map "\C-c\C-e" 'org-export) -;(define-key org-mode-map "\C-c\C-xa" 'org-export-as-ascii) -;(define-key org-mode-map "\C-c\C-x\C-a" 'org-export-as-ascii) -;(define-key org-mode-map "\C-c\C-xv" 'org-export-visible) -;(define-key org-mode-map "\C-c\C-x\C-v" 'org-export-visible) -;; OPML support is only an option for the future -;(define-key org-mode-map "\C-c\C-xo" 'org-export-as-opml) -;(define-key org-mode-map "\C-c\C-x\C-o" 'org-export-as-opml) -;(define-key org-mode-map "\C-c\C-xi" 'org-export-icalendar-this-file) -;(define-key org-mode-map "\C-c\C-x\C-i" 'org-export-icalendar-all-agenda-files) -;(define-key org-mode-map "\C-c\C-xc" 'org-export-icalendar-combine-agenda-files) -;(define-key org-mode-map "\C-c\C-x\C-c" 'org-export-icalendar-combine-agenda-files) -;(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-xoxo) -;(define-key org-mode-map "\C-c\C-x\C-x" 'org-export-as-xoxo) -;(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) (define-key org-mode-map "\C-c\C-x\C-k" 'org-cut-special) (define-key org-mode-map "\C-c\C-x\C-w" 'org-cut-special) @@ -14283,15 +15216,9 @@ a time), or the day by one (if it does not contain a time)." (define-key org-mode-map "\C-c\C-x\C-o" 'org-clock-out) (define-key org-mode-map "\C-c\C-x\C-x" 'org-clock-cancel) (define-key org-mode-map "\C-c\C-x\C-d" 'org-clock-display) - -;(define-key org-mode-map "\C-c\C-ef" 'org-publish-current-file) -;(define-key org-mode-map "\C-c\C-ep" 'org-publish-current-project) -;(define-key org-mode-map "\C-c\C-ec" 'org-publish) -;(define-key org-mode-map "\C-c\C-ea" 'org-publish-all) -;(define-key org-mode-map "\C-c\C-e\C-f" 'org-publish-current-file) -;(define-key org-mode-map "\C-c\C-e\C-p" 'org-publish-current-project) -;(define-key org-mode-map "\C-c\C-e\C-c" 'org-publish) -;(define-key org-mode-map "\C-c\C-e\C-a" 'org-publish-all) +(define-key org-mode-map "\C-c\C-x\C-r" 'org-clock-report) +(define-key org-mode-map "\C-c\C-x\C-u" 'org-dblock-update) +(define-key org-mode-map "\C-c\C-x\C-l" 'org-preview-latex-fragment) (when (featurep 'xemacs) (define-key org-mode-map 'button3 'popup-mode-menu)) @@ -14598,12 +15525,12 @@ This command does many different things, depending on context: (interactive "P") (let ((org-enable-table-editor t)) (cond - (org-clock-overlays + ((or org-clock-overlays org-occur-highlights + org-latex-fragment-image-overlays) (org-remove-clock-overlays) - (message "Clock overlays removed")) - (org-occur-highlights (org-remove-occur-highlights) - (message "occur highlights removed")) + (org-remove-latex-fragment-image-overlays) + (message "Temporary highlights/overlays removed from current buffer")) ((and (local-variable-p 'org-finish-function (current-buffer)) (fboundp org-finish-function)) (funcall org-finish-function)) @@ -14753,10 +15680,26 @@ See the individual commands for more information." ["Demote Heading" org-metaright (not (org-at-table-p))] ["Demote Subtree" org-shiftmetaright (not (org-at-table-p))] "--" - ["Archive Subtree" org-archive-subtree t] - "--" ["Convert to odd levels" org-convert-to-odd-levels t] ["Convert to odd/even levels" org-convert-to-oddeven-levels t]) + ("Archive" + ["Toggle ARCHIVE tag" org-toggle-archive-tag t] + ["Check and Tag Children" (org-toggle-archive-tag (4)) + :active t :keys "C-u C-c C-x C-a"] + ["Sparse trees open ARCHIVE trees" + (setq org-sparse-tree-open-archived-trees + (not org-sparse-tree-open-archived-trees)) + :style toggle :selected org-sparse-tree-open-archived-trees] + ["Cycling opens ARCHIVE trees" + (setq org-cycle-open-archived-trees (not org-cycle-open-archived-trees)) + :style toggle :selected org-cycle-open-archived-trees] + ["Agenda includes ARCHIVE trees" + (setq org-agenda-skip-archived-trees (not org-agenda-skip-archived-trees)) + :style toggle :selected (not org-agenda-skip-archived-trees)] + "--" + ["Move Subtree to Archive" org-archive-subtree t] + ["Check and Move Children" (org-archive-subtree '(4)) + :active t :keys "C-u C-c $"]) "--" ("TODO Lists" ["TODO/DONE/-" org-todo t] @@ -14785,6 +15728,7 @@ See the individual commands for more information." ["Clock out" org-clock-out t] ["Clock cancel" org-clock-cancel t] ["Display times" org-clock-display t] + ["Create clock table" org-clock-report t] "--" ["Record DONE time" (progn (setq org-log-done (not org-log-done)) @@ -14819,6 +15763,16 @@ See the individual commands for more information." (re-search-forward "<[a-z]+:" nil t))]) "--" ["Export/Publish" org-export t] + ("LaTeX" + ["Org CDLaTeX mode" org-cdlatex-mode :style toggle + :selected org-cdlatex-mode] + ["Insert Environment" cdlatex-environment (fboundp 'cdlatex-environment)] + ["Insert math symbol" cdlatex-math-symbol (fboundp 'cdlatex-math-symbol)] + ["Modify math symbol" org-cdlatex-math-modify + (org-inside-LaTeX-fragment-p)] + ["Export LaTeX fragments as images" + (setq org-export-with-LaTeX-fragments (not org-export-with-LaTeX-fragments)) + :style toggle :selected org-export-with-LaTeX-fragments]) "--" ("Documentation" ["Show Version" org-version t] @@ -14897,6 +15851,7 @@ contexts are: :tags on the TAGS in a headline :priority on the priority cookie in a headline :item on the first line of a plain list item +:item-bullet on the bullet/number of a plain list item :checkbox on the checkbox in a plain list item :table in an org-mode table :table-special on a special filed in a table @@ -14905,13 +15860,15 @@ contexts are: :keyword on a keyword: SCHEDULED, DEADLINE, CLOSE,COMMENT, QUOTE. :target on a <<target>> :radio-target on a <<<radio-target>>> +:latex-fragment on a LaTeX fragment +:latex-preview on a LaTeX fragment with overlayed preview image This function expects the position to be visible because it uses font-lock faces as a help to recognize the following contexts: :table-special, :link, and :keyword." (let* ((f (get-text-property (point) 'face)) (faces (if (listp f) f (list f))) - (p (point)) clist) + (p (point)) clist o) ;; First the large context (cond ((org-on-heading-p) @@ -14928,6 +15885,7 @@ and :keyword." (push (org-point-in-group p 0 :priority) clist))) ((org-at-item-p) + (push (org-point-in-group p 2 :item-bullet) clist) (push (list :item (point-at-bol) (save-excursion (org-end-of-item) (point))) clist) @@ -14961,7 +15919,19 @@ and :keyword." (goto-char (1- (match-beginning 0))) (if (looking-at org-radio-target-regexp) (push (org-point-in-group p 0 :radio-target) clist)) - (goto-char p))) + (goto-char p)) + ((setq o (car (delq nil + (mapcar + (lambda (x) + (if (memq x org-latex-fragment-image-overlays) x)) + (org-overlays-at (point)))))) + (push (list :latex-fragment + (org-overlay-start o) (org-overlay-end o)) clist) + (push (list :latex-preview + (org-overlay-start o) (org-overlay-end o)) clist)) + ((org-inside-LaTeX-fragment-p) + ;; FIXME: positions wring. + (push (list :latex-fragment (point) (point)) clist))) (setq clist (nreverse (delq nil clist))) clist)) @@ -15012,6 +15982,7 @@ return nil." ;; In the paragraph separator we include headlines, because filling ;; text in a line directly attached to a headline would otherwise ;; fill the headline as well. + (set (make-local-variable 'comment-start-skip) "^#+[ \t]*") (set (make-local-variable 'paragraph-separate) "\f\\|\\*\\|[ ]*$\\|[ \t]*[:|]") ;; The paragraph starter includes hand-formatted lists. (set (make-local-variable 'paragraph-start) @@ -15284,7 +16255,8 @@ When ENTRY is non-nil, show the entire entry." (forward-char -1) (if (memq (preceding-char) '(?\n ?\^M)) ;; leave blank line before heading - (forward-char -1)))))) + (forward-char -1))))) + (point)) (defun org-show-subtree () "Show everything after this heading at deeper levels." @@ -15336,9 +16308,8 @@ Show the heading too, if it is currently invisible." ;;; Experimental code - ;;; Finish up - + (provide 'org) (run-hooks 'org-load-hook) Binary files differ@@ -3,7 +3,7 @@ @setfilename ../info/org @settitle Org Mode Manual -@set VERSION 4.37 +@set VERSION 4.40 @set DATE June 2006 @dircategory Emacs @@ -83,9 +83,12 @@ Software Foundation raise funds for GNU development.'' * Timestamps:: Assign date and time to items * Tags:: Tagging headlines and matching sets of tags * Agenda views:: Collecting information into views +* Embedded LaTeX:: LaTeX fragments and formulas * Exporting:: Sharing and publishing of notes * Publishing:: Create a web site of linked Org-mode files * Miscellaneous:: All the rest which did not fit elsewhere +* Extensions and Hacking:: It is possible to write add-on code +* History and Acknowledgments:: How Org-mode came into being * Index:: The fast road to specific information * Key Index:: Key bindings and where they are described @@ -95,7 +98,7 @@ Software Foundation raise funds for GNU development.'' Introduction * Summary:: Brief summary of what Org-mode does -* Installation and activation:: How to install Org-mode +* Installation:: How to install Org-mode * Feedback:: Bug reports, ideas, patches etc. Document Structure @@ -109,6 +112,11 @@ Document Structure * Sparse trees:: Matches embedded in context * Plain lists:: Editing hand-formatted lists +Archiving + +* ARCHIVE tag:: Marking a tree as inactive +* Moving subtrees:: Moving a tree to an archive file + Tables * Built-in table editor:: Simple tables @@ -162,7 +170,7 @@ Timestamps Progress Logging -* Closing items:: When was this entry makred DONE? +* Closing items:: When was this entry marked DONE? * Clocking work time:: When exactly did you work on this item? Tags @@ -188,6 +196,14 @@ The weekly/daily agenda * Calendar/Diary integration:: Integrating Anniversaries and more * Sorting of agenda items:: The order of things +Embedded LaTeX + +* Math symbols:: TeX macros for symbols and Greek letters +* Subscripts and Superscripts:: Simple syntax for raising/lowering text +* LaTeX fragments:: Complex formulas made easy +* Processing LaTeX fragments:: Previewing LaTeX processing +* CDLaTeX mode:: Speed up entering of formulas + Exporting * ASCII export:: Exporting to plain ASCII @@ -211,7 +227,7 @@ Publishing Configuration * Project alist:: The central configuration variable -* File sources and destinations:: From here to there +* Sources and destinations:: From here to there * Selecting files:: What files are part of the project? * Publishing action:: Setting the function doing the publishing * Publishing options:: Tweaking HTML export @@ -227,21 +243,23 @@ Miscellaneous * Completion:: M-TAB knows what you need * Customization:: Adapting Org-mode to your taste -* Summary of in-buffer settings:: Using special lines to set options +* In-buffer settings:: Overview of the #+KEYWORDS * The very busy C-c C-c key:: When in doubt, press C-c C-c * Clean view:: Getting rid of leading stars in the outline * TTY keys:: Using Org-mode on a tty -* FAQ:: Frequently asked questions * Interaction:: Other Emacs packages * Bugs:: Things which do not work perfectly -* Acknowledgments:: These people provided feedback and more Interaction with other packages -* Extensions:: Third-party extensions for Org-mode * Cooperation:: Packages Org-mode cooperates with * Conflicts:: Packages that lead to conflicts +Extensions, Hooks and Hacking + +* Extensions:: Existing 3rd-part extensions +* Dynamic blocks:: Automatically filled blocks + @end detailmenu @end menu @@ -251,11 +269,11 @@ Interaction with other packages @menu * Summary:: Brief summary of what Org-mode does -* Installation and activation:: How to install Org-mode +* Installation:: How to install Org-mode * Feedback:: Bug reports, ideas, patches etc. @end menu -@node Summary, Installation and activation, Introduction, Introduction +@node Summary, Installation, Introduction, Introduction @section Summary @cindex summary @@ -296,14 +314,15 @@ example: The Org-mode table editor can be integrated into any major mode by activating the minor Orgtbl-mode. +@cindex FAQ There is a website for Org-mode which provides links to the newest -version of Org-mode, as well as additional information, screen shots -and example files. This page is located at +version of Org-mode, as well as additional information, frequently asked +questions (FAQ), links to tutorials etc. This page is located at @uref{http://www.astro.uva.nl/~dominik/Tools/org/}. @page -@node Installation and activation, Feedback, Summary, Introduction +@node Installation, Feedback, Summary, Introduction @section Installation and Activation @cindex installation @cindex autoload @@ -341,6 +360,10 @@ them together with @file{org-install.el} on your load path. Then add to (require 'org-install) @end lisp +If you use Org-mode with XEmacs, you also need to install the file +@file{noutline.el} from the @file{xemacs} subdirectory of the Org-mode +distribution. + @cindex org-mode, turning on With this setup, all files with extension @samp{.org} will be put into Org-mode. As an alternative, make the first line of a file look like @@ -354,7 +377,7 @@ MY PROJECTS -*- mode: org; -*- the file's name is. See also the variable @code{org-insert-mode-line-in-empty-file}. -@node Feedback, , Installation and activation, Introduction +@node Feedback, , Installation, Introduction @section Feedback @cindex feedback @cindex bug reports @@ -614,26 +637,89 @@ functionality. @node Archiving, Sparse trees, Structure editing, Document structure @section Archiving @cindex archiving -@cindex filing subtrees When a project represented by a (sub)tree is finished, you may want -to move the tree to an archive place, either in the same file under a -special top-level heading, or even to a different file. +to move the tree out of the way and to stop it from contributing to the +agenda. Org-mode knows two ways of archiving. You can mark a tree with +the ARCHIVE tag, or you can move an entire (sub)tree to a different +location. + +@menu +* ARCHIVE tag:: Marking a tree as inactive +* Moving subtrees:: Moving a tree to an archive file +@end menu + +@node ARCHIVE tag, Moving subtrees, Archiving, Archiving +@subsection The ARCHIVE tag +@cindex internal archiving + +A headline that is marked with the ARCHIVE tag (@pxref{Tags}) stays at +its location in the outline tree, but behaves in the following way: +@itemize @minus +@item +It does not open when you attempt to do so with a visibility cycling +command (@pxref{Visibility cycling}). You can still open it with a +normal outline command like @code{show-all}. Or you can modify the +option @code{org-cycle-open-archived-trees}. +@item +During sparse tree construction (@pxref{Sparse trees}), matches in +archived subtrees are not exposed, unless you configure the option +@code{org-sparse-tree-open-archived-trees}. +@item +During agenda view construction (@pxref{Agenda views}), the content of +archived trees is ignored unless you configure the option +@code{org-agenda-skip-archived-trees}. +@item +Archived trees are not exported (@pxref{Exporting}), only the headline +is. Configure the details using the variable +@code{org-export-with-archived-trees}. +@end itemize + +The following commands allow to set or clear the ARCHIVE tag: + +@table @kbd +@kindex C-c C-x C-a +@item C-c C-x C-a +Toggle the ARCHIVE tag for the current headline. When the tag is set, +the headline changes to a shadowish face, and the subtree below it is +hidden. +@kindex C-u C-c C-x C-a +@item C-u C-c C-x C-a +Check if any direct children of the current headline should be archived. +To do this, each subtree is checked for open TODO entries. If none are +found, the command offers to set the ARCHIVE tag for the child. If the +cursor is @emph{not} on a headline when this command is invoked, the +level 1 trees will be checked. +@end table + +@node Moving subtrees, , ARCHIVE tag, Archiving +@subsection Moving subtrees +@cindex external archiving + +Once an entire project is finished, you may want to move it to a +different location, either in the current file, or even in a different +file, the archive file. + @table @kbd @kindex C-c $ -@item @kbd{C-c $} +@item C-c $ Archive the subtree starting at the cursor position to the location given by @code{org-archive-location}. +@kindex C-u C-c $ +@item C-u C-c $ +Check if any direct children of the current headline could be moved to +the archive. To do this, each subtree is checked for open TODO entries. +If none are found, the command offers to move it to the archive +location. If the cursor is @emph{not} on a headline when this command +is invoked, the level 1 trees will be checked. @end table @cindex archive locations -The default archive is a file in the same directory as the current -file, with the name derived by appending @file{_archive} to the -current file name. For information and examples on how to change -this, see the documentation string of the variable -@code{org-archive-location}. If you are also using the Org-mode -agenda, archiving to a different file is a good way to keep archived -trees from contributing agenda items. +The default archive location is a file in the same directory as the +current file, with the name derived by appending @file{_archive} to the +current file name. For information and examples on how to change this, +see the documentation string of the variable +@code{org-archive-location}. @node Sparse trees, Plain lists, Archiving, Document structure @section Sparse trees @@ -806,6 +892,7 @@ checkbox. Otherwise, if this is an ordered list, renumber the ordered list at the cursor. @end table + @node Tables, Hyperlinks, Document structure, Top @chapter Tables @cindex tables @@ -1663,8 +1750,7 @@ selected words will form the basis of the search string. If the automatically created link is not working correctly or accurately enough, you can write custom functions to select the search string and to do the search for particular file types - see @ref{Custom searches}. -The key binding @kbd{C-c l} is only a suggestion - see @ref{Installation -and activation}. +The key binding @kbd{C-c l} is only a suggestion - see @ref{Installation}. @kindex C-c C-l @cindex link completion @@ -1674,7 +1760,11 @@ and activation}. Insert a link. This prompts for a link to be inserted into the buffer. You can just type a link, using text for an internal link, or one of the link type prefixes mentioned in the examples above. Through completion, -all links stored during the current session can be accessed. The link +all links stored during the current session can be +accessed@footnote{After insertion of a stored link, the link will be +removed from the list of stored links. To keep it in the list later +use, use a triple @kbd{C-u} prefix to @kbd{C-c C-l}, or configure the +option @code{org-keep-stored-link-after-insertion}.}. The link will be inserted into the buffer, along with a descriptive text. Note that you don't have to use this command to insert a link. Links in Org-mode are plain text, and you can type or paste them straight into @@ -1711,11 +1801,11 @@ When the cursor is on an internal link, this commands runs the corresponding search. When the cursor is on a TAG list in a headline, it creates the corresponding TAGS view. If the cursor is on a 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. +text and remote files in @samp{file:} links with Emacs and select a +suitable application for local non-text files. Classification of files +is based on file extension only. See option @code{org-file-apps}. If +you want to override the default application and visit the file with +Emacs, use a @kbd{C-u} prefix. @kindex mouse-2 @kindex mouse-1 @@ -2227,10 +2317,9 @@ brackets instead of angular brackets. @item Time range with CLOCK keyword @cindex CLOCK keyword When using the clock to time the work that is being done on specific -items, time ranges preceeded by the CLOCK keyword are inserted +items, time ranges preceded by the CLOCK keyword are inserted automatically into the file. The time stamps are enclosed in square brackets instead of angular brackets. @xref{Clocking work time}. -@c FIXME: Reference needed @end table @node Creating timestamps, Progress logging, Time stamps, Timestamps @@ -2376,7 +2465,7 @@ items in a project by starting and stopping a clock when you start and stop working on an aspect of a project. @menu -* Closing items:: When was this entry makred DONE? +* Closing items:: When was this entry marked DONE? * Clocking work time:: When exactly did you work on this item? @end menu @@ -2405,8 +2494,8 @@ each day, giving you an overview of what has been done on a day. Org-mode allows you to clock the time you spent on specific tasks in a project. When you start working on an item, you can start the clock. -When you stop working on that tast, or when you makr the task done, the -clock is stoppend and the corresponding time interval is recorded. It +When you stop working on that task, or when you mark the task done, the +clock is stopped and the corresponding time interval is recorded. It also computes the total time spent on each subtree of a project. @table @kbd @@ -2435,6 +2524,22 @@ puts overlays at the end of each headline, showing the total time recorded under that heading, including the time of any subheadings. You can use visibility cycling to study the tree, but the overlays disappear automatically when the buffer is changed. +@kindex C-c C-x C-r +@item C-c C-x C-r +Insert a dynamic block containing a clock report as an org-mode table +into the current file. +@example +#+BEGIN: clocktable :maxlevel 2 :emphasize nil + +#+END: clocktable +@end example +@noindent +If such a block already exists, its content is replaced by the new +table. The @samp{BEGIN} line can specify options: +@example +:maxlevels @r{Maximum level depth to which times are listed in the table.} +:emphasize @r{When @code{t}, emphasize level one and level two items} +@end example @end table The @kbd{l} key may be used in the timeline (@pxref{Timeline}) and in @@ -2612,7 +2717,7 @@ tagged @samp{:WORK:} or @samp{:LAPTOP:}. The string @samp{WORK|LAPTOP&NIGHT} requires that the @samp{:LAPTOP:} lines are also tagged @samp{NIGHT}. -@node Agenda views, Exporting, Tags, Top +@node Agenda views, Embedded LaTeX, Tags, Top @chapter Agenda Views @cindex agenda views @@ -2693,12 +2798,11 @@ to visit any of them. @cindex custom agenda commands @cindex agenda commands, custom The views are created through a dispatcher that should be bound to a -global key, for example @kbd{C-c a} (@pxref{Installation and -activation}). In the following we will assume that @kbd{C-c a} is -indeed how the dispatcher is accessed and list keyboard access to -commands accordingly. After pressing @kbd{C-c a}, an additional -letter is required to execute a command. The dispatcher offers the -following default commands: +global key, for example @kbd{C-c a} (@pxref{Installation}). In the +following we will assume that @kbd{C-c a} is indeed how the dispatcher +is accessed and list keyboard access to commands accordingly. After +pressing @kbd{C-c a}, an additional letter is required to execute a +command. The dispatcher offers the following default commands: @table @kbd @item a Create the calendar-like agenda (@pxref{Weekly/Daily agenda}). @@ -3092,6 +3196,10 @@ inheritance, this may be more than the tags listed in the line itself. @item : Set tags for the current headline. +@kindex a +@item a +Toggle the ARCHIVE tag for the current headline. + @kindex , @item , Set the priority for the current item. Org-mode prompts for the @@ -3208,7 +3316,206 @@ visit org files will not be removed. @end table -@node Exporting, Publishing, Agenda views, Top +@node Embedded LaTeX, Exporting, Agenda views, Top +@chapter Embedded LaTeX +@cindex @TeX{} interpretation +@cindex La@TeX{} interpretation + +Plain ASCII is normally sufficient for almost all note taking. One +exception, however, are scientific notes which need to be able to +contain mathematical symbols and the occasional formula. +La@TeX{}@footnote{La@TeX{} is a macro system based on Donald E. Knuth's +@TeX{} system. Many of the features described here as ``La@TeX{}'' are +really from @TeX{}, but for simplicity I am blurring this distinction.} +is widely used to typeset scientific documents. Org-mode supports +embedding La@TeX{} code into its files, because many academics are used +to read La@TeX{} source code, and because it can be readily processed +into images for HTML production. + +It is not necessary to mark La@TeX{} macros and code in any special way. +If you observe a few conventions, Org-mode knows how to find it and what +to do with it. + +@menu +* Math symbols:: TeX macros for symbols and Greek letters +* Subscripts and Superscripts:: Simple syntax for raising/lowering text +* LaTeX fragments:: Complex formulas made easy +* Processing LaTeX fragments:: Previewing LaTeX processing +* CDLaTeX mode:: Speed up entering of formulas +@end menu + +@node Math symbols, Subscripts and Superscripts, Embedded LaTeX, Embedded LaTeX +@section Math symbols + +You can use La@TeX{} macros to insert special symbols like @samp{\alpha} +to indicate the Greek letter, or @samp{\to} to indicate an arrow. +Completion for these macros is available, just type @samp{\} and maybe a +few letters, and press @kbd{M-@key{TAB}} to see possible completions. +Unlike La@TeX{} code, Org-mode allows these macros to be present +without surrounding math delimiters, for example: + +@example +Angles are written as Greek letters \alpha, \beta and \gamma. +@end example + +During HTML export (@pxref{HTML export}), these symbols are translated +into the proper syntax for HTML, for the above examples this is +@samp{α} and @samp{→}, respectively. + +@node Subscripts and Superscripts, LaTeX fragments, Math symbols, Embedded LaTeX +@section Subscripts and Superscripts + +Just like in La@TeX{}, @samp{^} and @samp{_} are used to indicate super- +and subscripts. Again, these can be used without embedding them in +math-mode delimiters. To increase the readability of ASCII text, it is +not necessary (but OK) to surround multi-character sub- and superscripts +with curly braces. For example + +@example +The mass if the sun is M_sun = 1.989 x 10^30 kg. The radius of +the sun is R_@{sun@} = 6.96 x 10^8 m. +@end example + +To avoid interpretation as raised or lowered text, you can quote +@samp{^} and @samp{_} with a backslash: @samp{\_} and @samp{\^}. + +During HTML export (@pxref{HTML export}), subscript and superscripts +are surrounded with @code{<sub>} and @code{<sup>} tags, respectively. + +@node LaTeX fragments, Processing LaTeX fragments, Subscripts and Superscripts, Embedded LaTeX +@section LaTeX fragments + +With symbols, sub- and superscripts, HTML is pretty much at its end when +it comes to representing mathematical formulas. More complex +expressions need a dedicated formula processor. To this end, Org-mode +can contain arbitrary La@TeX{} fragments. It provides commands to +preview the typeset result of these fragments, and upon export to HTML, +all fragments will be converted to images and inlined into the HTML +document. For this to work you need to be on a system with a working +La@TeX{} installation. You also need the @file{dvipng} program, +available at @url{http://sourceforge.net/projects/dvipng/}. + +La@TeX{} fragments don't need any special marking at all. The following +snippets will be identified as LaTeX source code: +@itemize @bullet +@item +Environments of any kind. The only requirement is that the +@code{\begin} statement appears on a new line, preceded by only +whitespace. +@item +Text within the usual La@TeX{} math delimiters. To avoid conflicts with +currency specifications, single @samp{$} characters are only recognized +as math delimiters if the enclosed text contains at most two line breaks, +is directly attached to the @samp{$} characters with no whitespace in +between, and if the closing @samp{$} is followed by whitespace or +punctuation. For the other delimiters, there is no such restriction, so +when in doubt, use @samp{\(...\)} as inline math delimiters. +@end itemize + +@noindent For example: + +@example +\begin@{equation@} % arbitrary environments, +x=\sqrt@{b@} % even tables, figures +\end@{equation@} % etc + +If $a^2=b$ and \( b=2 \), then the solution must be +either $$ a=+\sqrt@{2@} $$ or \[ a=-\sqrt@{2@} \]. +@end example + +@noindent +If you need any of the delimiter ASCII sequences for other purposes, you +can configure the option @code{org-format-latex-options} to deselect the +ones you do not wish to have interpreted by the La@TeX{} converter. + +@node Processing LaTeX fragments, CDLaTeX mode, LaTeX fragments, Embedded LaTeX +@section Processing LaTeX fragments + +La@TeX{} fragments can be processed to produce a preview images of the +typeset expressions: + +@table @kbd +@kindex C-c C-x C-l +@item C-c C-x C-l +Produce a preview image of the La@TeX{} fragment at point and overlay it +over the source code. If there is no fragment at point, process all +fragments in the current entry (between two headlines). When called +with a prefix argument, process the entire subtree. When called with +two prefix arguments, or when the cursor is before the first headline, +process the entire buffer. +@kindex C-c C-c +@item C-c C-c +Remove the overlay preview images. +@end table + +During HTML export (@pxref{HTML export}), all La@TeX{} fragments are +converted into images and inlined into the document if the following +setting is active: + +@lisp +(setq org-export-with-LaTeX-fragments t) +@end lisp + +@node CDLaTeX mode, , Processing LaTeX fragments, Embedded LaTeX +@section Using CDLaTeX to enter math + +CDLaTeX-mode is a minor mode that is normally used in combination with a +major LaTeX mode like AUCTeX in order to speed-up insertion of +environments and math templates. Inside Org-mode, you can make use of +some of the features of cdlatex-mode. You need to install +@file{cdlatex.el} and @file{texmathp.el} (the latter comes also with +AUCTeX) from @url{http://www.astro.uva.nl/~dominik/Tools/cdlatex}. +Don't turn cdlatex-mode itself under Org-mode, but use the light +version @code{org-cdlatex-mode} that comes as part of Org-mode. Turn it +on for the current buffer with @code{M-x org-cdlatex-mode}, or for all +Org-mode files with + +@lisp +(add-hook 'org-mode-hook 'turn-on-org-cdlatex) +@end lisp + +When this mode is enabled, the following features are present (for more +details see the documentation of cdlatex-mode): +@itemize @bullet +@kindex C-c @{ +@item +Environment templates can be inserted with @kbd{C-c @{}. +@item +@kindex @key{TAB} +The @key{TAB} key will do template expansion if the cursor is inside a +LaTeX fragment@footnote{Org-mode has a method to test if the cursor is +inside such a fragment, see the documentation of the function +@code{org-inside-LaTeX-fragment-p}.}. For example, @key{TAB} will +expand @code{fr} to @code{\frac@{@}@{@}} and position the cursor +correctly inside the first brace. Another @key{TAB} will get you into +the second brace. Even outside fragments, @key{TAB} will expand +environment abbreviations at the beginning of a line. For example, if +you write @samp{equ} at the beginning of a line and press @key{TAB}, +this abbreviation will be expanded to an @code{equation} environment. +To get a list of all abbreviations, type @kbd{M-x cdlatex-command-help}. +@item +@kindex _ +@kindex ^ +Pressing @kbd{_} and @kbd{^} inside a LaTeX fragment will insert these +characters together with a pair of braces. If you use @key{TAB} to move +out of the braces, and if the braces surround only a single character or +macro, they are removed again (depending on the variable +@code{cdlatex-simplify-sub-super-scripts}). +@item +@kindex ` +Pressing the backquote @kbd{`} followed by a character inserts math +macros, also outside LaTeX fragments. If you wait more than 1.5 seconds +after the backquote, a help window will pop up. +@item +@kindex ' +Pressing the normal quote @kbd{'} followed by another character modifies +the symbol before point with an accent or a font. If you wait more than +1.5 seconds after the backquote, a help window will pop up. Character +modification will work only inside La@TeX{} fragments, outside the quote +is normal. +@end itemize + +@node Exporting, Publishing, Embedded LaTeX, Top @chapter Exporting @cindex exporting @@ -3269,8 +3576,8 @@ at a different level, specify it with a prefix argument. For example, creates only top level headlines and does the rest as items. When headlines are converted to items, the indentation of the text following the headline is changed to fit nicely under the item. This is done with -the assumption that the first bodyline indicates the base indenation of -the body text. Any indenation larger than this is adjusted to preserve +the assumption that the first bodyline indicates the base indentation of +the body text. Any indentation larger than this is adjusted to preserve the layout relative to the first line. Should there be lines with less indentation than the first, these are left alone. @@ -3470,7 +3777,6 @@ formatting, this is true in particular for the HTML backend. Org-mode has a number of typing conventions that allow to produce a richly formatted output. - @itemize @bullet @cindex hand-formatted lists @@ -3484,22 +3790,14 @@ backend supports lists. See @xref{Plain lists}. @cindex bold text @cindex italic text @item -You can make words @b{*bold*}, @i{/italic/}, and _underlined_ +You can make words @b{*bold*}, @i{/italic/}, _underlined_, +@code{=code=}, and @samp{+strikethrough+}. -@cindex @TeX{} interpretation +@cindex LaTeX fragments, export +@cindex TeX macros, export @item -Simple @TeX{}-like math constructs are interpreted: - -@cindex completion, of @TeX{} symbols -@itemize @minus -@item -@samp{10^22} and @samp{J_n} are super- and subscripts. You can quote -@samp{^} and @samp{_} with a backslash: @samp{\_} and @samp{\^} -@item -@samp{\alpha} indicates a Greek letter, @samp{\to} an arrow. You can -use completion for these macros, just type @samp{\} and maybe a few -letters, and press @kbd{M-@key{TAB}} to see possible completions. -@end itemize +Many @TeX{} macros and entire La@TeX{} fragments are converted into HTML +entities or images (@pxref{Embedded LaTeX}). @cindex tables, export @item @@ -3531,6 +3829,7 @@ customization group @code{org-export-general}, and the following section which explains how to set export options with special lines in a buffer. + @node Export options, , Enhancing text, Text interpretation @subsection Export options @cindex options, for export @@ -3556,7 +3855,7 @@ Insert template with export options, see example below. #+LANGUAGE: language for HTML, e.g. @samp{en} (@code{org-export-default-language}) #+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 +#+OPTIONS: H:2 num:t toc:t \n:nil @@:t ::t |:t ^:t *:nil TeX:t LaTeX:t @end example @noindent @@ -3572,6 +3871,7 @@ you can: @cindex @TeX{}-like syntax for sub- and superscripts @cindex emphasized text @cindex @TeX{} macros +@cindex La@TeX{} fragments @example H: @r{set the number of headline levels for export} num: @r{turn on/off section-numbers} @@ -3582,11 +3882,13 @@ toc: @r{turn on/off table of contents} |: @r{turn on/off tables} ^: @r{turn on/off @TeX{}-like syntax for sub- and superscripts.} *: @r{turn on/off emphasized text (bold, italic, underlined)} -TeX: @r{turn on/off @TeX{} macros} +TeX: @r{turn on/off simple @TeX{} macros in plain text} +LaTeX: @r{turn on/off La@TeX{} fragments} @end example @node Publishing, Miscellaneous, Exporting, Top @chapter Publishing +@cindex publishing Org-mode includes@footnote{@file{org-publish.el} is not yet part of emacs, so if you are using @file{org.el} as it comes with Emacs, you @@ -3615,7 +3917,7 @@ and many other properties of a project. @menu * Project alist:: The central configuration variable -* File sources and destinations:: From here to there +* Sources and destinations:: From here to there * Selecting files:: What files are part of the project? * Publishing action:: Setting the function doing the publishing * Publishing options:: Tweaking HTML export @@ -3623,8 +3925,10 @@ and many other properties of a project. * Project page index:: Publishing a list of project files @end menu -@node Project alist, File sources and destinations, Configuration, Configuration +@node Project alist, Sources and destinations, Configuration, Configuration @subsection The variable @code{org-publish-project-alist} +@cindex org-publish-project-alist +@cindex projects, for publishing Org-publish is configured almost entirely through setting the value of one variable, called @code{org-publish-project-alist}. @@ -3649,8 +3953,9 @@ project, which group together files requiring different publishing options. When you publish such a ``meta-project'' all the components will also publish. -@node File sources and destinations, Selecting files, Project alist, Configuration +@node Sources and destinations, Selecting files, Project alist, Configuration @subsection Sources and destinations for files +@cindex directories, for publishing Most properties are optional, but some should always be set. In particular, org-publish needs to know where to look for source files, @@ -3664,8 +3969,9 @@ and where to put published files. @end multitable @noindent -@node Selecting files, Publishing action, File sources and destinations, Configuration +@node Selecting files, Publishing action, Sources and destinations, Configuration @subsection Selecting files +@cindex files, selecting for publishing By default, all files with extension @file{.org} in the base directory are considered part of the project. This can be modified by setting the @@ -3687,6 +3993,7 @@ and @code{:exclude}. @node Publishing action, Publishing options, Selecting files, Configuration @subsection Publishing Action +@cindex action, for publishing Publishing means that a file is copied to the destination directory and possibly transformed in the process. The default transformation is to @@ -3711,6 +4018,7 @@ provides one for attachments (files that only need to be copied): @node Publishing options, Publishing links, Publishing action, Configuration @subsection Options for the HTML exporter +@cindex options, for publishing The property list can be used to set many export options for the HTML exporter. In most cases, these properties correspond to user variables @@ -3723,9 +4031,11 @@ respective variable for details. @item @code{:headline-levels} @tab @code{org-export-headline-levels} @item @code{:section-numbers} @tab @code{org-export-with-section-numbers} @item @code{:table-of-contents} @tab @code{org-export-with-toc} +@item @code{:archived-trees} @tab @code{org-export-with-archived-trees} @item @code{:emphasize} @tab @code{org-export-with-emphasize} @item @code{:sub-superscript} @tab @code{org-export-with-sub-superscripts} @item @code{:TeX-macros} @tab @code{org-export-with-TeX-macros} +@item @code{:LaTeX-fragments} @tab @code{org-export-with-LaTeX-fragments} @item @code{:fixed-width} @tab @code{org-export-with-fixed-width} @item @code{:timestamps} .@tab @code{org-export-with-timestamps} @item @code{:tags} .@tab @code{org-export-with-tags} @@ -3752,6 +4062,7 @@ options}), however, override everything. @node Publishing links, Project page index, Publishing options, Configuration @subsection Links between published files +@cindex links, publishing To create a link from one Org-mode file to another, you would use something like @samp{[[file:foo.org][The foo]]} or simply @@ -3765,8 +4076,27 @@ careful with relative pathnames, and provided you have also configured org-publish to upload the related files, these links will work too. @ref{Complex example} for an example of this usage. +Sometime an Org-mode file to be published may contain links that are +only valid in your production environment, but not in the publishing +location. In this case, use the property + +@multitable @columnfractions 0.4 0.6 +@item @code{:link-validation-function} +@tab Function to validate links +@end multitable + +@noindent +to define a function for checking link validity. This function must +accept two arguments, the file name and a directory relative to which +the file name is interpreted in the production environment. If this +function returns @code{nil}, then the HTML generator will only insert a +description into the HTML file, but no link. One option for this +function is @code{org-publish-validate-link} which checks if the given +file is part of any project in @code{org-publish-project-alist}. + @node Project page index, , Publishing links, Configuration @subsection Project page index +@cindex index, of published pages The following properties may be used to control publishing of an index of files or summary page for a given project. @@ -3891,20 +4221,18 @@ Org uses timestamps to track when a file has changed. The above functions normally only publish changed files. You can override this and force publishing of all files by giving a prefix argument. -@node Miscellaneous, Index, Publishing, Top +@node Miscellaneous, Extensions and Hacking, Publishing, Top @chapter Miscellaneous @menu * Completion:: M-TAB knows what you need * Customization:: Adapting Org-mode to your taste -* Summary of in-buffer settings:: Using special lines to set options +* In-buffer settings:: Overview of the #+KEYWORDS * The very busy C-c C-c key:: When in doubt, press C-c C-c * Clean view:: Getting rid of leading stars in the outline * TTY keys:: Using Org-mode on a tty -* FAQ:: Frequently asked questions * Interaction:: Other Emacs packages * Bugs:: Things which do not work perfectly -* Acknowledgments:: These people provided feedback and more @end menu @node Completion, Customization, Miscellaneous, Miscellaneous @@ -3950,8 +4278,7 @@ Elsewhere, complete dictionary words using ispell. @end itemize @end table - -@node Customization, Summary of in-buffer settings, Completion, Miscellaneous +@node Customization, In-buffer settings, Completion, Miscellaneous @section Customization @cindex customization @cindex options, for customization @@ -3963,9 +4290,9 @@ describing the variables here. A structured overview of customization variables is available with @kbd{M-x org-customize}. Or select @code{Browse Org Group} from the @code{Org->Customization} menu. Many settings can also be activated on a per-file basis, by putting special -lines into the buffer (@pxref{Summary of in-buffer settings}). +lines into the buffer (@pxref{In-buffer settings}). -@node Summary of in-buffer settings, The very busy C-c C-c key, Customization, Miscellaneous +@node In-buffer settings, The very busy C-c C-c key, Customization, Miscellaneous @section Summary of in-buffer settings @cindex in-buffer settings @cindex special keywords @@ -4035,7 +4362,7 @@ These lines provide settings for exporting files. For more details see @ref{Export options}. @end table -@node The very busy C-c C-c key, Clean view, Summary of in-buffer settings, Miscellaneous +@node The very busy C-c C-c key, Clean view, In-buffer settings, Miscellaneous @section The very busy C-c C-c key @kindex C-c C-c @@ -4043,14 +4370,13 @@ The key @kbd{C-c C-c} has many purposes in org-mode, which are all mentioned scattered throughout this manual. One specific function of this key is to add @emph{tags} to a headline (@pxref{Tags}). In many other circumstances it means something like @emph{Hey Org-mode, look -here and update according to what you see here}. Here is a summary of what -this means in different contexts. +here and update according to what you see here}. Here is a summary of +what this means in different contexts. @itemize @minus -@c @item -@c If the cursor is in a headline, prompt for tags and insert them -@c into the current line, aligned to `org-tags-column'. When called -@c with prefix arg, realign all tags in the current buffer. +@item +If there are highlights in the buffer from the creation of a sparse +tree, or from clock display, remove these highlights. @item If the cursor is in one of the special @code{#+KEYWORD} lines, this triggers scanning the buffer for these lines and updating the @@ -4180,7 +4506,7 @@ double-star-per-level convention with @kbd{M-x org-convert-to-odd-levels RET} in that file. The reverse operation is @kbd{M-x org-convert-to-oddeven-levels}. -@node TTY keys, FAQ, Clean view, Miscellaneous +@node TTY keys, Interaction, Clean view, Miscellaneous @section Using org-mode on a tty @cindex tty keybindings @@ -4217,251 +4543,19 @@ rather use @kbd{C-c .} to re-insert the timestamp. @item @kbd{S-@key{down}} @tab @kbd{C-c C-x @key{down}} @tab @end multitable -@node FAQ, Interaction, TTY keys, Miscellaneous -@section Frequently asked questions -@cindex FAQ - -@enumerate -@cindex @code{keymapp nil} error -@item @b{When I try to use Org-mode, I always get -@code{(wrong-type-argument keymapp nil)}}.@* -@cindex allout.el, conflict with -This is a conflict with an outdated version of the @file{allout.el}. -See @ref{Conflicts}. - -@item @b{Org-mode seems to be a useful default mode for the various -@file{README} files I have scattered through my directories. How do I -turn it on for all @file{README} files?} - -@lisp -(add-to-list 'auto-mode-alist '("README$" . org-mode)) -@end lisp - -@item @b{I would like to use editing features of org-mode in other -modes, is this possible?}@* -@c -Not really. For tables there is @code{orgtbl-mode} which implements the -table editor as a minor mode. For other features you need to switch to -Org-mode temporarily, or prepare text in a different buffer. - -@item @b{Can I get the visibility-cycling features in outline-mode and -outline-minor-mode?}@* -@c -Yes, these functions are written in a way that they are independent of -the outline setup. The following setup provides standard Org-mode -functionality in outline-mode on @key{TAB} and @kbd{S-@key{TAB}}. For -outline-minor-mode, we use @kbd{C-@key{TAB}} instead of @key{TAB}, -because @key{TAB} usually has mode-specific tasks. -@lisp -(add-hook 'outline-minor-mode-hook - (lambda () - (define-key outline-minor-mode-map [(control tab)] 'org-cycle) - (define-key outline-minor-mode-map [(shift tab)] 'org-global-cycle))) -(add-hook 'outline-mode-hook - (lambda () - (define-key outline-mode-map [(tab)] 'org-cycle) - (define-key outline-mode-map [(shift tab)] 'org-global-cycle))) -@end lisp - -Or check out @file{outline-magic.el}, which does this and also provides -promotion and demotion functionality. @file{outline-magic.el} is -available at @url{http://www.astro.uva.nl/~dominik/Tools/OutlineMagic}. - -@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?}@* -@c -These must be links in plain text, containing white space, such as -@samp{bbdb:Richard Stallman}. You need to protect these links by -putting double brackets around them, like @samp{[[bbdb:Richard -Stallman]]}. - -@item @b{I see that Org-mode now creates links using the double bracket -convention that hides the link part and the brackets, only showing the -description part. How can I convert my old links to this new format?}@* -@c -Execute once in each Org-mode file: @kbd{M-x org-upgrade-old-links}. -This replaces angular brackets with the new link format. - -@item @b{I don't care if you find the new bracket links great, I am -attached to the old style using angular brackets and no hiding of the -link text. Please give them back to me, don't tell me it is not -possible!}@* -@c -Would I let you down like that? If you must, you can do this - -@lisp -(setq org-link-style 'plain - org-link-format "<%s>") -@end lisp - -@item @b{When I am executing shell/elisp links I always get a -confirmation prompt and need to type @kbd{yes @key{RET}}, that's 4 key -presses! Can I get rid of this?}@* -@c -@cindex shell links, confirmation -@cindex dangerous commands -The confirmation is there to protect you from unwantingly execute -potentially dangerous commands. For example, imagine a link -@samp{[[shell:rm -rf ~/*][Google Search]]}. In an Org-mode buffer, this -command would look like @samp{Google Search}, but really it would remove -your home directory. If you wish, you can make it easier to respond to -the query by setting @code{org-confirm-shell-link-function} and/or -@code{org-confirm-elisp-link-function} to @code{y-or-n-p}. Then a -single @kbd{y} keypress will be enough to confirm those links. It is -also possible to turn off this check entirely, but I do not recommend to -do this. Be warned. - -@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?}@* -@c -See @ref{Clean view}. - -@item @b{I would like to have two windows on the same Org-mode -file, but with different outline visibility. Is that possible?}@* -@c -@cindex @code{make-indirect-buffer} -@cindex indirect buffers -In GNU Emacs, you may use @emph{indirect buffers} which do exactly this. -See the documentation on the command @code{make-indirect-buffer}. In -XEmacs, this is currently not possible because of the different outline -implementation. - -@item @b{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?}@* -@c -If you plan to use ASCII or HTML export, make sure things you want to -be exported as item lists are level 4 at least, even if that does mean -there is a level jump. For example: - -@example -* Todays top priorities -**** TODO write a letter to xyz -**** TODO Finish the paper -**** Pick up kids at the school -@end example - -Alternatively, if you need a specific value for the heading/item -transition in a particular file, use the @samp{+OPTIONS} line to -configure the @samp{H} switch. - -@example -+OPTIONS: H:2; ... -@end example - -@item @b{I would like to export only a subtree of my file to HTML. -How?}@* -@c -@cindex exporting a subtree -If you want to export a subtree, mark the subtree as region and then -export. Marking can be done with @kbd{C-c @@ C-x C-x}, for example. - -@item @b{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 @ref{Conflicts}. - -@item @b{One of my table columns has started to fill up with -@samp{#ERROR}. What is going on?}@* -@c -Org-mode tried to compute the column from other fields using a -formula stored in the @samp{#+TBLFM:} line just below the table, and -the evaluation of the formula fails. Fix the fields used in the -formula, or fix the formula, or remove it! - -@item @b{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 -@i{before} the horizontal line. How can I quickly move to the line -@i{below} the horizontal line instead?}@* -@c -Press @key{down} (to get on the separator line) and then @key{TAB}. -Or configure the variable @code{org-table-tab-jumps-over-hlines}. - -@item @b{How can I change the indentation of an entire table without -fixing every line by hand?}@* -@c -@cindex indentation, of tables -The indentation of a table is set by the first line. So just fix the -indentation of the first line and realign with @key{TAB}. - -@item @b{Is it possible to include entries from org-mode files into my -emacs diary?}@* -@c -Since the org-mode agenda is much more powerful and can contain the -diary (@pxref{Calendar/Diary integration}), you should think twice -before deciding to do this. Integrating Org-mode information into the -diary is, however, possible. You need to turn on @emph{fancy diary -display} by setting in @file{.emacs}: - -@lisp -(add-hook 'diary-display-hook 'fancy-diary-display) -@end lisp - -Then include the following line into your @file{~/diary} file, in -order to get the entries from all files listed in the variable -@code{org-agenda-files}: - -@example -&%%(org-diary) -@end example -@noindent -You may also select specific files with - -@example -&%%(org-diary) ~/path/to/some/org-file.org -&%%(org-diary) ~/path/to/another/org-file.org -@end example - -If you now launch the calendar and press @kbd{d} to display a diary, the -headlines of entries containing a timestamp, date range, schedule, or -deadline referring to the selected date will be listed. Just like -Org-mode's agenda view, the diary for @emph{today} contains additional -entries for overdue deadlines and scheduled items. See also the -documentation of the @command{org-diary} function. Under XEmacs, it is -not possible to jump back from the diary to the org, this works only in -the agenda buffer. - -@end enumerate - - -@node Interaction, Bugs, FAQ, Miscellaneous +@node Interaction, Bugs, TTY keys, Miscellaneous @section Interaction with other packages @cindex packages, interaction with other Org-mode lives in the world of GNU Emacs and interacts in various ways with other code out there. @menu -* Extensions:: Third-party extensions for Org-mode * Cooperation:: Packages Org-mode cooperates with * Conflicts:: Packages that lead to conflicts @end menu -@node Extensions, Cooperation, Interaction, Interaction -@subsection Third-party extensions for Org-mode - -The following extensions for Org-mode have been written by other people: - -@table @asis -@cindex @file{org-mouse.el} -@item @file{org-mouse.el} by Piotr Zielinski -This package implements extended mouse functionality for Org-mode. It -allows you to cycle visibility and to edit the document structure with -the mouse. Best of all, it provides a context-sensitive menu on -@key{mouse-3} that changes depending on the context of a mouse-click. -@file{org-mouse.el} is freely available at @url{http://www.cl.cam.ac.uk/~pz215/files/org-mouse.el}. -@cindex @file{org-publish.el} -@item @file{org-publish.el} by David O'Toole -This package provides facilities for publishing related sets of Org-mode -files together with linked files like images as a webpages. It is -highly configurable and can be used for other publishing purposes as -well. As of Org-mode version 4.30, @file{org-publish.el} is part of -the Org-mode distribution. It is not yet part of Emacs, however, due to -a pending copyright assignment. In the mean time, @file{org-publish.el} -can be downloaded from David's site: -@url{http://dto.freeshell.org/e/org-publish.el}. -@end table -@node Cooperation, Conflicts, Extensions, Interaction +@node Cooperation, Conflicts, Interaction, Interaction @subsection Packages that Org-mode cooperates with @table @asis @@ -4487,6 +4581,11 @@ at @url{http://www.astro.uva.nl/~dominik/Tools}. Org-mode checks for the function @code{constants-get}, which has to be autoloaded in your setup. See the installation instructions in the file @file{constants.el}. +@item @file{cdlatex.el} by Carsten Dominik +@cindex @file{cdlatex.el} +Org-mode can make use of the cdlatex package to efficiently enter +La@TeX{} fragments into Org-mode files. +@file{cdlatex.el} is not part of Emacs, find it on the web. @item @file{remember.el} by John Wiegley @cindex @file{remember.el} Org mode cooperates with remember, see @ref{Remember}. @@ -4538,7 +4637,7 @@ in the paragraph above about CUA mode also applies here. @end table -@node Bugs, Acknowledgments, Interaction, Miscellaneous +@node Bugs, , Interaction, Miscellaneous @section Bugs @cindex bugs @@ -4564,10 +4663,6 @@ When the application called by @kbd{C-c C-o} to open a file link fails (for example because the application does not exist or refuses to open the file), it does so silently. No error message is displayed. @item -Plain list items should be able to hold a TODO item. Unfortunately this -has so many technical problems that I will only consider this change for -the next major release (5.0). -@item The remote-editing commands in the agenda buffer cannot be undone with @code{undo} called from within the agenda buffer. But you can go to the corresponding buffer (using @key{TAB} or @key{RET} and execute @@ -4577,22 +4672,144 @@ Recalculating a table line applies the formulas from left to right. If a formula uses @emph{calculated} fields further down the row, multiple recalculation may be needed to get all fields consistent. @item -Several words in a row may @b{*be made bold*}, but this does not work if -the string is distributed over two lines. +A single letter cannot be made bold, for example @samp{*a*}. @item The exporters work well, but could be made more efficient. @end itemize -@node Acknowledgments, , Bugs, Miscellaneous -@section Acknowledgments + +@node Extensions and Hacking, History and Acknowledgments, Miscellaneous, Top +@appendix Extensions, Hooks and Hacking + +This appendix lists extensions for Org-mode written by other authors. +It also covers some aspects where users can easily extend the +functionality of Org-mode. + +@menu +* Extensions:: Existing 3rd-part extensions +* Dynamic blocks:: Automatically filled blocks +@end menu + +@node Extensions, Dynamic blocks, Extensions and Hacking, Extensions and Hacking +@section Third-party extensions for Org-mode + +The following extensions for Org-mode have been written by other people: + +@table @asis +@cindex @file{org-mouse.el} +@item @file{org-mouse.el} by Piotr Zielinski +This package implements extended mouse functionality for Org-mode. It +allows you to cycle visibility and to edit the document structure with +the mouse. Best of all, it provides a context-sensitive menu on +@key{mouse-3} that changes depending on the context of a mouse-click. +@file{org-mouse.el} is freely available at @url{http://www.cl.cam.ac.uk/~pz215/files/org-mouse.el}. +@cindex @file{org-publish.el} +@item @file{org-publish.el} by David O'Toole +This package provides facilities for publishing related sets of Org-mode +files together with linked files like images as a webpages. It is +highly configurable and can be used for other publishing purposes as +well. As of Org-mode version 4.30, @file{org-publish.el} is part of the +Org-mode distribution. It is not yet part of Emacs, however, a delay +caused by the preparations for the 22.1 release. In the mean time, +@file{org-publish.el} can be downloaded from David's site: +@url{http://dto.freeshell.org/e/org-publish.el}. +@cindex @file{org-blog.el} +@item @file{org-blog.el} by David O'Toole +A blogging plug-in for @file{org-publish.el}. +@url{http://dto.freeshell.org/notebook/OrgMode.html}. +@cindex @file{org-blogging.el} +@item @file{org-blogging.el} by Bastien Guerry +Publish Org-mode files as +blogs. @url{http://www.cognition.ens.fr/~guerry/org-blogging.html}. +@end table + +@node Dynamic blocks, , Extensions, Extensions and Hacking +@section Dynamic blocks + +Org-mode documents can contain @emph{dynamic blocks}. These are +specially marked regions that are updates by some user-written +function. A good example for such a block is the clock table inserted +by the command @kbd{C-c C-x C-r} (@pxref{Clocking work time}). + +Dynamic block are enclosed by a BEGIN-END structure that assigns a name +to the block and can also specify parameters for the function producing +the content of the block. + +@example +#+BEGIN: myblock :parameter1 value1 :parameter2 value2 ..... + +#+END: +@end example + +Dynamic blocks are updated with the following commands + +@table @kbd +@kindex C-c C-x C-u +@item C-c C-x C-u +Update dynamic block at point. +@kindex C-u C-c C-x C-u +@item C-u C-c C-x C-u +Update all dynamic blocks in the current file. +@end table + +Updating a dynamic block means to remove all the text between BEGIN and +END, parse the BEGIN line for parameters and then call the specific +writer function for this block to insert the new content. For a block +with name @code{myblock}, the writer function is +@code{org-dblock-write:myblock} with as only parameter a property list +with the parameters given in the begin line. Here is a trivial example +of a block that keeps track of when the block update function was last +run: + +@example +#+BEGIN: block-update-time :format "on %m/%d/%Y at %H:%M" + +#+END: +@end example + +@noindent +The corresponding block writer function could look like this: + +@lisp +(defun org-dblock-write:date-and-time (params) + (let ((fmt (or (plist-get params :format) "%d. %m. %Y"))) + (insert "Last block update at: " + (format-time-string fmt (current-time))))) +@end lisp + +If you want to make sure that all dynamic blocks are always up-to-date, +you could add the function @code{org-update-all-dblocks} to a hook, for +example @code{before-save-hook}. @code{org-update-all-dblocks} is +written in a way that is does nothing in buffers that are not in Org-mode. + + +@node History and Acknowledgments, Index, Extensions and Hacking, Top +@appendix History and Acknowledgments @cindex acknowledgments +@cindex history @cindex thanks -Org-mode was created by @value{AUTHOR}, who still maintains it at the -Org-mode homepage @uref{http://www.astro.uva.nl/~dominik/Tools/org/}. -The following people (in alphabetic order) have helped the development -along with ideas, suggestions and patches. Many thanks to all of you, -Org-mode would not be what it is without your input. +The beginnings of Org-mode go back to 2003. It was borne out of +frustration over the user interface of the emacs outline-mode. All I +wanted was to make working with an outline tree possible without having +to remember more than 10 commands just for hiding and unhiding parts of +the outline tree, and to allow to restructure a tree easily. Visibility +cycling and structure editing were originally implemented in the package +@file{outline-magic.el}, but quickly moved to the more general +@file{org.el}. TODO entries, basic time stamps, and table support were +added next, and highlight the two main goals that Org-mode still has +today: To create a new, outline-based, plain text mode with innovative +and intuitive editing features, and to incorporate project planning +functionality directly into a notes file. + +Since the first release, hundreds of emails to me or on +@code{emacs-orgmode@@gnu.org} have provided a constant stream of bug +reports, feedback, new ideas, and sometimes even patches and add-on +code. Many thanks to everyone who has helped to improve this package. +I am trying to keep here a list of the people who had significant +influence in shaping one or more aspects of Org-mode. The list may not +be complete, if I have forgotten someone, please accept my apologies and +let me know. @itemize @bullet @item @@ -4607,8 +4824,9 @@ for Remember. @i{Pavel Chalmoviansky} influenced the agenda treatment of items with specified time. @item -@i{Gregory Chenov} patched support for lisp forms into table -calculations and improved XEmacs compatibility. +@i{Gregory Chernov} patched support for lisp forms into table +calculations and improved XEmacs compatibility, in particular by porting +@file{nouline.el} to XEmacs. @item @i{Sacha Chua} suggested to copy some linking code from Planner. @item @@ -4619,9 +4837,15 @@ patched CSS formatting into the HTML exporter, and inspired the agenda. @item @i{Nic Ferrier} contributed mailcap and XOXO support. @item +@i{Niels Giessen} had the idea to automatically archive DONE trees. +@item +@i{Bastien Guerry} provoded extensive feedback. +@item @i{Kai Grossjohann} pointed out key-binding conflicts caused by Org-mode. @item +@i{Leon Liu} asked for embedded LaTeX and tested it. +@item @i{Stefan Monnier} provided a patch to keep the Emacs-Lisp compiler happy. @item @@ -4656,6 +4880,9 @@ other things. Linking to VM/BBDB/GNUS was inspired by @i{Tom Shannon}'s @file{organizer-mode.el}. @item +@i{Daniel Sinder} came up with the idea of internal archiving by locking +subtrees. +@item @i{David O'Toole} wrote @file{org-publish.el} and drafted the manual chapter about publishing. @item @@ -4684,9 +4911,10 @@ work on a tty. @i{Piotr Zielinski} wrote @file{org-mouse.el} and showed how to follow links with mouse-1. @end itemize - -@node Index, Key Index, Miscellaneous, Top -@chapter Index + + +@node Index, Key Index, History and Acknowledgments, Top +@unnumbered Index @printindex cp diff --git a/orgcard.pdf b/orgcard.pdf Binary files differindex 2327538..813a1ac 100644 --- a/orgcard.pdf +++ b/orgcard.pdf diff --git a/orgcard.tex b/orgcard.tex index 646a03b..a97d024 100644 --- a/orgcard.tex +++ b/orgcard.tex @@ -1,5 +1,5 @@ % Reference Card for Org Mode -\def\orgversionnumber{4.37} +\def\orgversionnumber{4.40} \def\year{2006} % %**start of header @@ -288,10 +288,8 @@ are preserved on all copies. \section{Motion} -\key{next heading}{C-c C-n} -\key{previous heading}{C-c C-p} -\key{next heading, same level}{C-c C-f} -\key{previous heading, same level}{C-c C-b} +\key{next/previous heading}{C-c C-n/p} +\key{next/previous heading, same level}{C-c C-f/b} \key{backward to higher level heading}{C-c C-u} \key{jump to another place in document}{C-c C-j} \key{previous/next plain list item}{S-UP/DOWN$^3$} @@ -306,13 +304,18 @@ are preserved on all copies. \key{promote current subtree up one level}{M-S-LEFT} \key{demote current subtree down one level}{M-S-RIGHT} -\key{move subtree/list item up}{M-S-UP} -\key{move subtree/list item down}{M-S-DOWN} +\key{move subtree/list item up/down}{M-S-UP/DOWN} \key{kill subtree}{C-c C-x C-w} \key{copy subtree}{C-c C-x M-w} \key{yank subtree}{C-c C-x C-y} +\key{narrow buffer to current subtree}{C-x n s} -\key{archive subtree}{C-c \$} +\section{Archiving} + +\key{toggle ARCHIVE tag}{C-c C-x C-a} +\metax{mark fully dine children}{C-u C-c C-x C-a} +\key{move subtree to achive file}{C-c \$} +\key{move all fully done children}{C-u C-c \$} To set archive location for current file, add a line like$^2$: \vskip -1mm \beginexample% @@ -329,18 +332,8 @@ To set archive location for current file, add a line like$^2$: %\key{agenda for the week}{C-c a$^1$} %\key{agenda for date at cursor}{C-c C-o} -\section{Tags} - -\key{set tags for current heading}{C-c C-c} -\key{realign tags in all headings}{C-u C-c C-c} -\key{create sparse tree with matching tags}{C-c \\} -\key{globally (agenda) match tags at cursor}{C-c C-o} - \section{Tables} -%Org-mode has its own built-in intuitive table editor with unique -%capabilities. - {\bf Creating a table} %\metax{insert a new Org-mode table}{M-x org-table-create} @@ -466,6 +459,39 @@ formula, \kbd{:=} a named-field formula. %\key{\kbd{vm://myself@some.where.org/folder\#id}}{\rm VM remote} +\section{Remember-mode Integration} + +See the manual for how to make remember.el use Org-mode links and +files. The note-finishing command \kbd{C-c C-c} will first prompt for +an org file. In the file, find a location with: + +\key{rotate subtree visibility}{TAB} +\key{next heading}{DOWN} +\key{previous heading}{UP} + +Insert the note with one of the following: + +\key{as sublevel of heading at cursor}{RET} +\key{right here (cursor not on heading)}{RET} +\key{before current heading}{LEFT} +\key{after current heading}{RIGHT} +\key{shortcut to end of buffer (cursor at buf-start)}{RET} +\key{Abort}{q} + +\section{Completion} + +In-buffer completion completes TODO keywords at headline start, TeX +macros after ``{\tt \\}'', option keywords after ``{\tt \#-}'', TAGS +after ``{\tt :}'', and dictionary words elsewhere. + +\key{Complete word at point}{M-TAB} + + +\newcolumn +\title{Org-Mode Reference Card (2/2)} + +\centerline{(for version \orgversionnumber)} + \section{TODO Items} \key{rotate the state of the current item}{C-c C-t} @@ -480,6 +506,13 @@ formula, \kbd{:=} a named-field formula. \key{\kbd{\#+SEQ_TODO: TODO TRY BLUFF DONE}}{\rm todo workflow} \key{\kbd{\#+TYP_TODO: Phil home work DONE}}{\rm todo types} +\section{Tags} + +\key{set tags for current heading}{C-c C-c} +\key{realign tags in all headings}{C-u C-c C-c} +\key{create sparse tree with matching tags}{C-c \\} +\key{globally (agenda) match tags at cursor}{C-c C-o} + \section{Timestamps} \key{prompt for date and insert timestamp}{C-c .} @@ -502,18 +535,26 @@ formula, \kbd{:=} a named-field formula. %\key{... forward/backward one month}{M-S-LEFT/RIGT} -\newcolumn -\title{Org-Mode Reference Card (2/2)} - -\centerline{(for version \orgversionnumber)} - \section{Clocking Time} \key{start clock on current item}{C-c C-x C-i} \key{stop clock on current item}{C-c C-x C-o} \key{cancel current clock}{C-c C-x C-x} + \key{display total subtree times}{C-c C-x C-d} \key{remove displayed times}{C-c C-c} +\key{insert/update table with clock report}{C-c C-x C-r} + +\section{Dynamic Blocks} + +\key{update dynamic block at point}{C-c C-x C-u} +\metax{update all dynamic blocks}{C-u C-c C-x C-u} + +\section{LaTeX and cdlatex-mode} + +\key{preview LaTeX fragment}{C-c C-x C-l} +\key{Expand abbreviation (cdlatex-mode)}{TAB} +\key{Insert/modify math symbol (cdlatex-mode)}{` / '} \section{Agenda Views} @@ -565,6 +606,7 @@ To set categories, add lines like$^2$: \key{change state of current TODO item}{t} \key{show tags of current headline}{T} \key{set tags for current headline}{:} +\key{toggle ARCHIVE tag}{a} \key{set priority of current item}{p} \key{raise/lower priority of current item}{S-UP/DOWN$^3$} \key{display weighted priority of current item}{P} @@ -577,7 +619,6 @@ To set categories, add lines like$^2$: \key{Stop the clock (clock-out)}{O} \key{Cancel current clock}{X} -\newcolumn {\bf Calendar commands} @@ -593,6 +634,13 @@ To set categories, add lines like$^2$: \key{quit agenda, remove agenda buffer}{q} \key{exit agenda, remove all agenda buffers}{x} +\section{Calendar and Diary Integration} + +To include entries from the Emacs diary in your Org-mode agenda: +\beginexample% +(setq org-agenda-include-diary t) +\endexample + \section{Exporting and Publishing} Exporting creates files with extensions {\it .txt\/} and {\it .html\/} @@ -629,18 +677,19 @@ keywords. {\tt M-TAB} again just after keyword is complete inserts examples. \key{language code for html}{\#+LANGUAGE:} \key{free text description of file}{\#+TEXT:} \key{... which can carry over multiple lines}{\#+TEXT:} -\key{settings for the export process - see below}{\#+OPTIONS:} - -\key{set number of headline levels for export}{H:2} -\key{turn on/off section numbers}{num:t} -\key{turn on/off table of contents}{toc:t} -\key{turn on/off linebreak preservation}{\\n:nil} -\key{turn on/off quoted html tags}{@:t} -\key{turn on/off fixed width sections}{::t} -\key{turn on/off tables}{|:t} -\key{turn on/off \TeX\ syntax for sub/super-scripts}{\^{}:t} -\key{turn on/off emphasised text}{*:nil} -\key{turn on/off \TeX\ macros}{TeX:t} +%\key{settings for the export process - see below}{\#+OPTIONS:} +\key{settings for the export process}{\#+OPTIONS:} + +%\key{set number of headline levels for export}{H:2} +%\key{turn on/off section numbers}{num:t} +%\key{turn on/off table of contents}{toc:t} +%\key{turn on/off linebreak preservation}{\\n:nil} +%\key{turn on/off quoted html tags}{@:t} +%\key{turn on/off fixed width sections}{::t} +%\key{turn on/off tables}{|:t} +%\key{turn on/off \TeX\ syntax for sub/super-scripts}{\^{}:t} +%\key{turn on/off emphasised text}{*:nil} +%\key{turn on/off \TeX\ macros}{TeX:t} {\bf Comments: Text not being exported} @@ -651,53 +700,20 @@ Subtrees whose header starts with COMMENT are never exported. \key{toggle COMMENT keyword on entry}{C-c ;} -\section{Completion} - -In-buffer completion completes TODO keywords at headline start, TeX -macros after ``{\tt \\}'', option keywords after ``{\tt \#-}'', TAGS -after ``{\tt :}'', and dictionary words elsewhere. - -\key{Complete word at point}{M-TAB} - -\section{Calendar and Diary Integration} -To include entries from the Emacs diary in your Org-mode agenda: -\beginexample% -(setq org-agenda-include-diary t) -\endexample - -\section{Remember-mode Integration} +%\section{CUA and pc-select compatibility}% -See the manual for how to make remember.el use Org-mode links and -files. The note-finishing command \kbd{C-c C-c} will first prompt for -an org file. In the file, find a location with: - -\key{rotate subtree visibility}{TAB} -\key{next heading}{DOWN} -\key{previous heading}{UP} - -Insert the note with one of the following: - -\key{as sublevel of heading at cursor}{RET} -\key{right here (cursor not on heading)}{RET} -\key{before current heading}{LEFT} -\key{after current heading}{RIGHT} -\key{shortcut to end of buffer (cursor at buf-start)}{RET} -\key{Abort}{q} - -\section{CUA and pc-select compatibility} - -Configure the variable {\tt org-CUA-compatibility} to make Org-mode -avoid the \kbd{S-<cursor>} bindings used by these modes. When set, -Org-mode will change the following keybindings (also in the agenda -buffer, but not during date selection). See note mark four$^3$ -throughout the reference card. -%\vskip-mm -\beginexample -S-UP $\to$ M-p S-DOWN $\to$ M-n -S-LEFT $\to$ M-- S-RIGHT $\to$ M-+ -S-RET $\to$ C-S-RET -\endexample +%Configure the variable {\tt org-CUA-compatibility} to make Org-mode +%avoid the \kbd{S-<cursor>} bindings used by these modes. When set, +%Org-mode will change the following keybindings (also in the agenda +%buffer, but not during date selection). See note mark four$^3$ +%throughout the reference card. +%%\vskip-mm +%\beginexample +%S-UP $\to$ M-p S-DOWN $\to$ M-n +%S-LEFT $\to$ M-- S-RIGHT $\to$ M-+ +%S-RET $\to$ C-S-RET +%\endexample \section{Notes} $^1$ This is only a suggestion for a binding of this command. Choose diff --git a/xemacs/README b/xemacs/README new file mode 100644 index 0000000..70d2c1e --- /dev/null +++ b/xemacs/README @@ -0,0 +1,9 @@ +This directory contains files that are necessary or at least useful +companions for Org-mode: + +noutline.el Greg Chernov's port of the overlay-based implementation of + outline-mode. This is requires, and until XEmacs uses + this (or another port), you need to install it with Org-mode. + +ps-print-invisible.el Greg Chernovs modification to ps-print, to + honor invisible text properties during printing.
\ No newline at end of file diff --git a/xemacs/noutline.el b/xemacs/noutline.el new file mode 100644 index 0000000..2e11ee5 --- /dev/null +++ b/xemacs/noutline.el @@ -0,0 +1,1051 @@ +;;; outline.el --- outline mode commands for Emacs + +;; ---------------------------------------------------------------------- +;; This is a port of GNU Emacs outline.el to XEmacs. The port was +;; done by Greg Chernov and is temporarily made available on the Org-mode +;; homepage http://www.astro.uva.nl/~dominik/Tools/org/, and as part +;; of the Org-mode distribution. +;; ---------------------------------------------------------------------- + +;; Copyright (C) 1986, 1993, 1994, 1995, 1997, 2000, 2001, 2002, +;; 2003, 2004, 2005 Free Software Foundation, Inc. + +;; Maintainer: FSF +;; Keywords: outlines + +;; This file is part of GNU Emacs. + +;; GNU Emacs is free software; you can redistribute it and/or modify +;; it under the terms of the GNU General Public License as published by +;; the Free Software Foundation; either version 2, or (at your option) +;; any later version. + +;; GNU Emacs is distributed in the hope that it will be useful, +;; but WITHOUT ANY WARRANTY; without even the implied warranty of +;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +;; GNU General Public License for more details. + +;; You should have received a copy of the GNU General Public License +;; along with GNU Emacs; see the file COPYING. If not, write to the +;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, +;; Boston, MA 02110-1301, USA. + +;;; Commentary: + +;; This package is a major mode for editing outline-format documents. +;; An outline can be `abstracted' to show headers at any given level, +;; with all stuff below hidden. See the Emacs manual for details. + +;;; Todo: + +;; - subtree-terminators +;; - better handle comments before function bodies (i.e. heading) +;; - don't bother hiding whitespace + +;;; Code: + +(require 'easymenu) + +;; XEmacs and compatibility + +(defalias 'match-string-no-properties 'match-string) + +(if (not (fboundp 'add-to-invisibility-spec)) + (defun add-to-invisibility-spec (arg) + "Add elements to `buffer-invisibility-spec'. +See documentation for `buffer-invisibility-spec' for the kind of elements +that can be added." + (if (eq buffer-invisibility-spec t) + (setq buffer-invisibility-spec (list t))) + (setq buffer-invisibility-spec + (cons arg buffer-invisibility-spec)))) + +(if (not (fboundp 'remove-from-invisibility-spec)) + (defun remove-from-invisibility-spec (arg) + "Remove elements from `buffer-invisibility-spec'." + (if (consp buffer-invisibility-spec) + (setq buffer-invisibility-spec + (delete arg buffer-invisibility-spec))))) + +(defvar font-lock-warning-face) + + +(defgroup outlines nil + "Support for hierarchical outlining." + :prefix "outline-" + :group 'editing) + +(defcustom outline-regexp "[*\^L]+" + "*Regular expression to match the beginning of a heading. +Any line whose beginning matches this regexp is considered to start a heading. +Note that Outline mode only checks this regexp at the start of a line, +so the regexp need not (and usually does not) start with `^'. +The recommended way to set this is with a Local Variables: list +in the file it applies to. See also `outline-heading-end-regexp'." + :type '(choice regexp (const nil)) + :group 'outlines) + +(defcustom outline-heading-end-regexp "\n" + "*Regular expression to match the end of a heading line. +You can assume that point is at the beginning of a heading when this +regexp is searched for. The heading ends at the end of the match. +The recommended way to set this is with a `Local Variables:' list +in the file it applies to." + :type 'regexp + :group 'outlines) + +(defvar outline-mode-prefix-map + (let ((map (make-sparse-keymap))) + (define-key map "@" 'outline-mark-subtree) + (define-key map "\C-n" 'outline-next-visible-heading) + (define-key map "\C-p" 'outline-previous-visible-heading) + (define-key map "\C-i" 'show-children) + (define-key map "\C-s" 'show-subtree) + (define-key map "\C-d" 'hide-subtree) + (define-key map "\C-u" 'outline-up-heading) + (define-key map "\C-f" 'outline-forward-same-level) + (define-key map "\C-b" 'outline-backward-same-level) + (define-key map "\C-t" 'hide-body) + (define-key map "\C-a" 'show-all) + (define-key map "\C-c" 'hide-entry) + (define-key map "\C-e" 'show-entry) + (define-key map "\C-l" 'hide-leaves) + (define-key map "\C-k" 'show-branches) + (define-key map "\C-q" 'hide-sublevels) + (define-key map "\C-o" 'hide-other) + (define-key map "\C-^" 'outline-move-subtree-up) + (define-key map "\C-v" 'outline-move-subtree-down) + (define-key map [(control ?<)] 'outline-promote) + (define-key map [(control ?>)] 'outline-demote) + (define-key map "\C-m" 'outline-insert-heading) + ;; Where to bind outline-cycle ? + map)) + + + +(defvar outline-mode-menu-heading + '("Headings" + ["Up" outline-up-heading t] + ["Next" outline-next-visible-heading t] + ["Previous" outline-previous-visible-heading t] + ["Next Same Level" outline-forward-same-level t] + ["Previous Same Level" outline-backward-same-level t] + ["New heading" outline-insert-heading t] + ["Copy to kill ring" outline-headers-as-kill :active (region-active-p)] + ["Move subtree up" outline-move-subtree-up t] + ["Move subtree down" outline-move-subtree-down t] + ["Promote subtree" outline-promote t] + ["Demote subtree" outline-demote t])) + +(defvar outline-mode-menu-show + '("Show" + ["Show All" show-all t] + ["Show Entry" show-entry t] + ["Show Branches" show-branches t] + ["Show Children" show-children t] + ["Show Subtree" show-subtree t])) + +(defvar outline-mode-menu-hide + '("Hide" + ["Hide Leaves" hide-leaves t] + ["Hide Body" hide-body t] + ["Hide Entry" hide-entry t] + ["Hide Subtree" hide-subtree t] + ["Hide Other" hide-other t] + ["Hide Sublevels" hide-sublevels t])) + + + +(defvar outline-mode-map + (let ((map (make-sparse-keymap))) + (define-key map "\C-c" outline-mode-prefix-map) + map)) + +(defvar outline-font-lock-keywords + '(;; + ;; Highlight headings according to the level. + (eval . (list (concat "^\\(?:" outline-regexp "\\).+") + 0 '(outline-font-lock-face) nil t))) + "Additional expressions to highlight in Outline mode.") + +(defface outline-1 + '((t (:foreground "Blue1"))) + "Level 1." + :group 'outlines) + +(defface outline-2 + '((t (:foreground "DarkGoldenrod"))) + "Level 2." + :group 'outlines) + +(defface outline-3 + '((t (:foreground "Purple"))) + "Level 3." + :group 'outlines) + +(defface outline-4 + '((t (:foreground "Firebrick"))) + "Level 4." + :group 'outlines) + +(defface outline-5 + '((t (:foreground "ForestGreen"))) + "Level 5." + :group 'outlines) + +(defface outline-6 + '((t (:foreground "CadetBlue"))) + "Level 6." + :group 'outlines) + +(defface outline-7 + '((t (:foreground "Orchid"))) + "Level 7." + :group 'outlines) + +(defface outline-8 + '((t (:foreground "RosyBrown"))) + "Level 8." + :group 'outlines) + + + +(defvar outline-font-lock-faces + [outline-1 outline-2 outline-3 outline-4 + outline-5 outline-6 outline-7 outline-8]) + +(defvar outline-font-lock-levels nil) +(make-variable-buffer-local 'outline-font-lock-levels) + +(defun outline-font-lock-face () + ;; (save-excursion + ;; (outline-back-to-heading t) + ;; (let* ((count 0) + ;; (start-level (funcall outline-level)) + ;; (level start-level) + ;; face-level) + ;; (while (not (setq face-level + ;; (if (or (bobp) (eq level 1)) 0 + ;; (cdr (assq level outline-font-lock-levels))))) + ;; (outline-up-heading 1 t) + ;; (setq count (1+ count)) + ;; (setq level (funcall outline-level))) + ;; ;; Remember for later. + ;; (unless (zerop count) + ;; (setq face-level (+ face-level count)) + ;; (push (cons start-level face-level) outline-font-lock-levels)) + ;; (condition-case nil + ;; (aref outline-font-lock-faces face-level) + ;; (error font-lock-warning-face)))) + (save-excursion + (goto-char (match-beginning 0)) + (looking-at outline-regexp) + (condition-case nil + (aref outline-font-lock-faces (1- (funcall outline-level))) + (error font-lock-warning-face)))) + +(defvar outline-view-change-hook nil + "Normal hook to be run after outline visibility changes.") + +(defvar outline-mode-hook nil + "*This hook is run when outline mode starts.") + +(defvar outline-blank-line nil + "*Non-nil means to leave unhidden blank line before heading.") + +;;;###autoload +(define-derived-mode outline-mode text-mode "Outline" + "Set major mode for editing outlines with selective display. +Headings are lines which start with asterisks: one for major headings, +two for subheadings, etc. Lines not starting with asterisks are body lines. + +Body text or subheadings under a heading can be made temporarily +invisible, or visible again. Invisible lines are attached to the end +of the heading, so they move with it, if the line is killed and yanked +back. A heading with text hidden under it is marked with an ellipsis (...). + +Commands:\\<outline-mode-map> +\\[outline-next-visible-heading] outline-next-visible-heading move by visible headings +\\[outline-previous-visible-heading] outline-previous-visible-heading +\\[outline-forward-same-level] outline-forward-same-level similar but skip subheadings +\\[outline-backward-same-level] outline-backward-same-level +\\[outline-up-heading] outline-up-heading move from subheading to heading + +\\[hide-body] make all text invisible (not headings). +\\[show-all] make everything in buffer visible. +\\[hide-sublevels] make only the first N levels of headers visible. + +The remaining commands are used when point is on a heading line. +They apply to some of the body or subheadings of that heading. +\\[hide-subtree] hide-subtree make body and subheadings invisible. +\\[show-subtree] show-subtree make body and subheadings visible. +\\[show-children] show-children make direct subheadings visible. + No effect on body, or subheadings 2 or more levels down. + With arg N, affects subheadings N levels down. +\\[hide-entry] make immediately following body invisible. +\\[show-entry] make it visible. +\\[hide-leaves] make body under heading and under its subheadings invisible. + The subheadings remain visible. +\\[show-branches] make all subheadings at all levels visible. + +The variable `outline-regexp' can be changed to control what is a heading. +A line is a heading if `outline-regexp' matches something at the +beginning of the line. The longer the match, the deeper the level. + +Turning on outline mode calls the value of `text-mode-hook' and then of +`outline-mode-hook', if they are non-nil." + (make-local-variable 'line-move-ignore-invisible) + (setq line-move-ignore-invisible t) + ;; Cause use of ellipses for invisible text. + (add-to-invisibility-spec '(outline . t)) + + (easy-menu-add outline-mode-menu-heading) + (easy-menu-add outline-mode-menu-show) + (easy-menu-add outline-mode-menu-hide) + (set (make-local-variable 'paragraph-start) + (concat paragraph-start "\\|\\(?:" outline-regexp "\\)")) + ;; Inhibit auto-filling of header lines. + (set (make-local-variable 'auto-fill-inhibit-regexp) outline-regexp) + (set (make-local-variable 'paragraph-separate) + (concat paragraph-separate "\\|\\(?:" outline-regexp "\\)")) + (set (make-local-variable 'font-lock-defaults) + '(outline-font-lock-keywords t nil nil backward-paragraph)) + (setq imenu-generic-expression + (list (list nil (concat "^\\(?:" outline-regexp "\\).*$") 0))) + (add-hook 'change-major-mode-hook 'show-all nil t)) + +(defcustom outline-minor-mode-prefix "\C-c@" + "*Prefix key to use for Outline commands in Outline minor mode. +The value of this variable is checked as part of loading Outline mode. +After that, changing the prefix key requires manipulating keymaps." + :type 'string + :group 'outlines) + +;;;###autoload +(define-minor-mode outline-minor-mode + "Toggle Outline minor mode. +With arg, turn Outline minor mode on if arg is positive, off otherwise. +See the command `outline-mode' for more information on this mode." + nil " Outl" (list (cons outline-minor-mode-prefix outline-mode-prefix-map)) + :group 'outlines + (if outline-minor-mode + (progn + ;; Turn off this mode if we change major modes. + (easy-menu-add outline-mode-menu-heading) + (easy-menu-add outline-mode-menu-show) + (easy-menu-add outline-mode-menu-hide) + (add-hook 'change-major-mode-hook + (lambda () (outline-minor-mode -1)) + nil t) + (set (make-local-variable 'line-move-ignore-invisible) t) + ;; Cause use of ellipses for invisible text. + (add-to-invisibility-spec '(outline . t))) + (easy-menu-remove outline-mode-menu-heading) + (easy-menu-remove outline-mode-menu-show) + (easy-menu-remove outline-mode-menu-hide) + (setq line-move-ignore-invisible nil) + ;; Cause use of ellipses for invisible text. + (remove-from-invisibility-spec '(outline . t)) + ;; When turning off outline mode, get rid of any outline hiding. + (show-all))) + +(defvar outline-level 'outline-level + "*Function of no args to compute a header's nesting level in an outline. +It can assume point is at the beginning of a header line and that the match +data reflects the `outline-regexp'.") + +(defvar outline-heading-alist () + "Alist associating a heading for every possible level. +Each entry is of the form (HEADING . LEVEL). +This alist is used two ways: to find the heading corresponding to +a given level and to find the level of a given heading. +If a mode or document needs several sets of outline headings (for example +numbered and unnumbered sections), list them set by set and sorted by level +within each set. For example in texinfo mode: + + (setq outline-heading-alist + '((\"@chapter\" . 2) (\"@section\" . 3) (\"@subsection\" . 4) + (\"@subsubsection\" . 5) + (\"@unnumbered\" . 2) (\"@unnumberedsec\" . 3) + (\"@unnumberedsubsec\" . 4) (\"@unnumberedsubsubsec\" . 5) + (\"@appendix\" . 2) (\"@appendixsec\" . 3)... + (\"@appendixsubsec\" . 4) (\"@appendixsubsubsec\" . 5) ..)) + +Instead of sorting the entries in each set, you can also separate the +sets with nil.") +(make-variable-buffer-local 'outline-heading-alist) + +;; This used to count columns rather than characters, but that made ^L +;; appear to be at level 2 instead of 1. Columns would be better for +;; tab handling, but the default regexp doesn't use tabs, and anyone +;; who changes the regexp can also redefine the outline-level variable +;; as appropriate. +(defun outline-level () + "Return the depth to which a statement is nested in the outline. +Point must be at the beginning of a header line. +This is actually either the level specified in `outline-heading-alist' +or else the number of characters matched by `outline-regexp'." + (or (cdr (assoc (match-string 0) outline-heading-alist)) + (- (match-end 0) (match-beginning 0)))) + +(defun outline-next-preface () + "Skip forward to just before the next heading line. +If there's no following heading line, stop before the newline +at the end of the buffer." + (if (re-search-forward (concat "\n\\(?:" outline-regexp "\\)") + nil 'move) + (goto-char (match-beginning 0))) + (if (and (bolp) (or outline-blank-line (eobp)) (not (bobp))) + (forward-char -1))) + +(defun outline-next-heading () + "Move to the next (possibly invisible) heading line." + (interactive) + ;; Make sure we don't match the heading we're at. + (if (and (bolp) (not (eobp))) (forward-char 1)) + (if (re-search-forward (concat "^\\(?:" outline-regexp "\\)") + nil 'move) + (goto-char (match-beginning 0)))) + +(defun outline-previous-heading () + "Move to the previous (possibly invisible) heading line." + (interactive) + (re-search-backward (concat "^\\(?:" outline-regexp "\\)") + nil 'move)) + +(defsubst outline-invisible-p (&optional pos) + "Non-nil if the character after point is invisible." + (get-char-property (or pos (point)) 'invisible)) + +(defun outline-visible () + (not (outline-invisible-p))) +(make-obsolete 'outline-visible 'outline-invisible-p) + +(defun outline-back-to-heading (&optional invisible-ok) + "Move to previous heading line, or beg of this line if it's a heading. +Only visible heading lines are considered, unless INVISIBLE-OK is non-nil." + (beginning-of-line) + (or (outline-on-heading-p invisible-ok) + (let (found) + (save-excursion + (while (not found) + (or (re-search-backward (concat "^\\(?:" outline-regexp "\\)") + nil t) + (error "before first heading")) + (setq found (and (or invisible-ok (not (outline-invisible-p))) + (point))))) + (goto-char found) + found))) + +(defun outline-on-heading-p (&optional invisible-ok) + "Return t if point is on a (visible) heading line. +If INVISIBLE-OK is non-nil, an invisible heading line is ok too." + (save-excursion + (beginning-of-line) + (and (bolp) (or invisible-ok (not (outline-invisible-p))) + (looking-at outline-regexp)))) + +(defun outline-insert-heading () + "Insert a new heading at same depth at point." + (interactive) + (let ((head (save-excursion + (condition-case nil + (outline-back-to-heading) + (error (outline-next-heading))) + (if (eobp) + (or (caar outline-heading-alist) "") + (match-string 0))))) + (unless (or (string-match "[ \t]\\'" head) + (not (string-match (concat "\\`\\(?:" outline-regexp "\\)") + (concat head " ")))) + (setq head (concat head " "))) + (unless (bolp) (end-of-line) (newline)) + (insert head) + (unless (eolp) + (save-excursion (newline-and-indent))) + (run-hooks 'outline-insert-heading-hook))) + +(defun outline-invent-heading (head up) + (save-match-data + ;; Let's try to invent one by repeating or deleting the last char. + (let ((new-head (if up (substring head 0 -1) + (concat head (substring head -1))))) + (if (string-match (concat "\\`\\(?:" outline-regexp "\\)") + new-head) + ;; Why bother checking that it is indeed higher/lower level ? + new-head + ;; Didn't work, so ask what to do. + (read-string (format "%s heading for `%s': " + (if up "Parent" "Demoted") head) + head nil nil))))) + +(defun outline-promote (&optional children) + "Promote headings higher up the tree. +If prefix argument CHILDREN is given, promote also all the children. +If the region is active in `transient-mark-mode', promote all headings +in the region." + (interactive + (list (if (and zmacs-regions (region-active-p)) 'region + (outline-back-to-heading) + (if current-prefix-arg nil 'subtree)))) + (cond + ((eq children 'region) + (outline-map-region 'outline-promote (region-beginning) (region-end))) + (children + (outline-map-region 'outline-promote + (point) + (save-excursion (outline-get-next-sibling) (point)))) + (t + (outline-back-to-heading t) + (let* ((head (match-string-no-properties 0)) + (level (save-match-data (funcall outline-level))) + (up-head (or (outline-head-from-level (1- level) head) + ;; Use the parent heading, if it is really + ;; one level less. + (save-excursion + (save-match-data + (outline-up-heading 1 t) + (and (= (1- level) (funcall outline-level)) + (match-string-no-properties 0)))) + ;; Bummer!! There is no lower level heading. + (outline-invent-heading head 'up)))) + + (unless (rassoc level outline-heading-alist) + (push (cons head level) outline-heading-alist)) + + (replace-match up-head nil t))))) + +(defun outline-demote (&optional children) + "Demote headings lower down the tree. +If prefix argument CHILDREN is given, demote also all the children. +If the region is active in `transient-mark-mode', demote all headings +in the region." + (interactive + (list (if (and zmacs-regions (region-active-p)) 'region + (outline-back-to-heading) + (if current-prefix-arg nil 'subtree)))) + (cond + ((eq children 'region) + (outline-map-region 'outline-demote (region-beginning) (region-end))) + (children + (outline-map-region 'outline-demote + (point) + (save-excursion (outline-get-next-sibling) (point)))) + (t + (let* ((head (match-string-no-properties 0)) + (level (save-match-data (funcall outline-level))) + (down-head + (or (outline-head-from-level (1+ level) head) + (save-excursion + (save-match-data + (while (and (progn (outline-next-heading) (not (eobp))) + (<= (funcall outline-level) level))) + (when (eobp) + ;; Try again from the beginning of the buffer. + (goto-char (point-min)) + (while (and (progn (outline-next-heading) (not (eobp))) + (<= (funcall outline-level) level)))) + (unless (eobp) + (looking-at outline-regexp) + (match-string-no-properties 0)))) + ;; Bummer!! There is no higher-level heading in the buffer. + (outline-invent-heading head nil)))) + + (unless (rassoc level outline-heading-alist) + (push (cons head level) outline-heading-alist)) + (replace-match down-head nil t))))) + +(defun outline-head-from-level (level head &optional alist) + "Get new heading with level LEVEL from ALIST. +If there are no such entries, return nil. +ALIST defaults to `outline-heading-alist'. +Similar to (car (rassoc LEVEL ALIST)). +If there are several different entries with same new level, choose +the one with the smallest distance to the assocation of HEAD in the alist. +This makes it possible for promotion to work in modes with several +independent sets of headings (numbered, unnumbered, appendix...)" + (unless alist (setq alist outline-heading-alist)) + (let ((l (rassoc level alist)) + ll h hl l2 l2l) + (cond + ((null l) nil) + ;; If there's no HEAD after L, any other entry for LEVEL after L + ;; can't be much better than L. + ((null (setq h (assoc head (setq ll (memq l alist))))) (car l)) + ;; If there's no other entry for LEVEL, just keep L. + ((null (setq l2 (rassoc level (cdr ll)))) (car l)) + ;; Now we have L, L2, and H: see if L2 seems better than L. + ;; If H is after L2, L2 is better. + ((memq h (setq l2l (memq l2 (cdr ll)))) + (outline-head-from-level level head l2l)) + ;; Now we have H between L and L2. + ;; If there's a separator between L and H, prefer L2. + ((memq h (memq nil ll)) + (outline-head-from-level level head l2l)) + ;; If there's a separator between L2 and H, prefer L. + ((memq l2 (memq nil (setq hl (memq h ll)))) (car l)) + ;; No separator between L and L2, check the distance. + ((< (* 2 (length hl)) (+ (length ll) (length l2l))) + (outline-head-from-level level head l2l)) + ;; If all else fails, just keep L. + (t (car l))))) + +(defun outline-map-region (fun beg end) + "Call FUN for every heading between BEG and END. +When FUN is called, point is at the beginning of the heading and +the match data is set appropriately." + (save-excursion + (setq end (copy-marker end)) + (goto-char beg) + (when (re-search-forward (concat "^\\(?:" outline-regexp "\\)") end t) + (goto-char (match-beginning 0)) + (funcall fun) + (while (and (progn + (outline-next-heading) + (< (point) end)) + (not (eobp))) + (funcall fun))))) + +;; Vertical tree motion + +(defun outline-move-subtree-up (&optional arg) + "Move the currrent subtree up past ARG headlines of the same level." + (interactive "p") + (outline-move-subtree-down (- arg))) + +(defun outline-move-subtree-down (&optional arg) + "Move the currrent subtree down past ARG headlines of the same level." + (interactive "p") + (let ((movfunc (if (> arg 0) 'outline-get-next-sibling + 'outline-get-last-sibling)) + (ins-point (make-marker)) + (cnt (abs arg)) + (tmp-string "") + beg end folded) + ;; Select the tree + (outline-back-to-heading) + (setq beg (point)) + (save-match-data + (save-excursion (outline-end-of-heading) + (setq folded (outline-invisible-p))) + (outline-end-of-subtree)) + (if (= (char-after) ?\n) (forward-char 1)) + (setq end (point)) + ;; Find insertion point, with error handling + (goto-char beg) + (while (> cnt 0) + (or (funcall movfunc) + (progn (goto-char beg) + (error "Cannot move past superior level"))) + (setq cnt (1- cnt))) + (if (> arg 0) + ;; Moving forward - still need to move over subtree + (progn (outline-end-of-subtree) + (if (= (char-after) ?\n) (forward-char 1)))) + (move-marker ins-point (point)) + (setq tmp-string (buffer-substring beg end)) + (delete-region beg end) + (insert tmp-string) + (goto-char ins-point) + (if folded (hide-subtree)) + (move-marker ins-point nil))) + +(defun outline-end-of-heading () + (if (re-search-forward outline-heading-end-regexp nil 'move) + (forward-char -1))) + +(defun outline-next-visible-heading (arg) + "Move to the next visible heading line. +With argument, repeats or can move backward if negative. +A heading line is one that starts with a `*' (or that +`outline-regexp' matches)." + (interactive "p") + (if (< arg 0) + (beginning-of-line) + (end-of-line)) + (while (and (not (bobp)) (< arg 0)) + (while (and (not (bobp)) + (re-search-backward (concat "^\\(?:" outline-regexp "\\)") + nil 'move) + (outline-invisible-p))) + (setq arg (1+ arg))) + (while (and (not (eobp)) (> arg 0)) + (while (and (not (eobp)) + (re-search-forward (concat "^\\(?:" outline-regexp "\\)") + nil 'move) + (outline-invisible-p (match-beginning 0)))) + (setq arg (1- arg))) + (beginning-of-line)) + +(defun outline-previous-visible-heading (arg) + "Move to the previous heading line. +With argument, repeats or can move forward if negative. +A heading line is one that starts with a `*' (or that +`outline-regexp' matches)." + (interactive "p") + (outline-next-visible-heading (- arg))) + +(defun outline-mark-subtree () + "Mark the current subtree in an outlined document. +This puts point at the start of the current subtree, and mark at the end." + (interactive) + (let ((beg)) + (if (outline-on-heading-p) + ;; we are already looking at a heading + (beginning-of-line) + ;; else go back to previous heading + (outline-previous-visible-heading 1)) + (setq beg (point)) + (outline-end-of-subtree) + (push-mark (point) nil t) + (goto-char beg))) + + +(defun outline-discard-extents (&optional beg end) + "Clear BEG and END of overlays whose property NAME has value VAL. +Overlays might be moved and/or split. +BEG and END default respectively to the beginning and end of buffer." + (unless beg (setq beg (point-min))) + (unless end (setq end (point-max))) + (if (< end beg) + (setq beg (prog1 end (setq end beg)))) + (save-excursion + (map-extents + #'(lambda (ex ignored) + (if (< (extent-start-position ex) beg) + (if (> (extent-end-position ex) end) + (progn + (set-extent-endpoints (copy-extent ex) + (extent-start-position ex) beg) + (set-extent-endpoints ex end (extent-end-position ex))) + (set-extent-endpoints ex (extent-start-position ex) beg))) + (if (> (extent-end-position ex) end) + (set-extent-endpoints ex end (extent-end-position ex)) + (delete-extent ex))) + (current-buffer) beg end nil 'end-closed 'outline))) + + +;;;(defun outline-discard-extents (from to) +;;; "Delete hideshow extents in region defined by FROM and TO." +;;; (when (< to from) +;;; (setq from (prog1 to (setq to from)))) +;;; (map-extents #'(lambda (ex ignored) (delete-extent ex)) +;;; (current-buffer) from to nil 'end-closed 'outline)) + +(defun outline-flag-region (from to flag) + "Hide or show lines from FROM to TO, according to FLAG. +If FLAG is nil then text is shown, while if FLAG is t the text is hidden." + (when (< to from) + (setq from (prog1 to (setq to from)))) + ;; first clear it all out + (outline-discard-extents from to) + (when flag + (let ((ex (make-extent from to))) + (set-extent-property ex 'invisible 'outline) + (set-extent-property ex 'outline flag) + (set-extent-property ex 'isearch-open-invisible 'outline-isearch-open-invisible))) + ;; Seems only used by lazy-lock. I.e. obsolete. + (run-hooks 'outline-view-change-hook)) + + + +;; Function to be set as an outline-isearch-open-invisible' property +;; to the overlay that makes the outline invisible (see +;; `outline-flag-region'). +(defun outline-isearch-open-invisible (overlay) + ;; We rely on the fact that isearch places point on the matched text. + (show-entry)) + +(defun hide-entry () + "Hide the body directly following this heading." + (interactive) + (save-excursion + (outline-back-to-heading) + (outline-end-of-heading) + (outline-flag-region (point) (progn (outline-next-preface) (point)) t))) + +(defun show-entry () + "Show the body directly following this heading. +Show the heading too, if it is currently invisible." + (interactive) + (save-excursion + (outline-back-to-heading t) + (outline-flag-region (max 1 (1- (point))) + (progn (outline-next-preface) (point)) nil))) + +(defun hide-body () + "Hide all body lines in buffer, leaving all headings visible." + (interactive) + (hide-region-body (point-min) (point-max))) + +(defun hide-region-body (start end) + "Hide all body lines in the region, but not headings." + ;; Nullify the hook to avoid repeated calls to `outline-flag-region' + ;; wasting lots of time running `lazy-lock-fontify-after-outline' + ;; and run the hook finally. + (let (outline-view-change-hook) + (save-excursion + (save-restriction + (narrow-to-region start end) + (goto-char (point-min)) + (if (outline-on-heading-p) + (outline-end-of-heading) + (outline-next-preface)) + (while (not (eobp)) + (outline-flag-region (point) + (progn (outline-next-preface) (point)) t) + (unless (eobp) + (forward-char (if (looking-at "\n\n") 2 1)) + (outline-end-of-heading)))))) + (run-hooks 'outline-view-change-hook)) + +(defun show-all () + "Show all of the text in the buffer." + (interactive) + (outline-flag-region (point-min) (point-max) nil)) + +(defun hide-subtree () + "Hide everything after this heading at deeper levels." + (interactive) + (outline-flag-subtree t)) + +(defun hide-leaves () + "Hide all body after this heading at deeper levels." + (interactive) + (save-excursion + (outline-back-to-heading) + (outline-end-of-heading) + (hide-region-body (point) (progn (outline-end-of-subtree) (point))))) + +(defun show-subtree () + "Show everything after this heading at deeper levels." + (interactive) + (outline-flag-subtree nil)) + +(defun outline-show-heading () + "Show the current heading and move to its end." + (outline-flag-region (- (point) + (if (bobp) 0 + (if (and outline-blank-line + (eq (char-before (1- (point))) ?\n)) + 2 1))) + (progn (outline-end-of-heading) (point)) + nil)) + +(defun hide-sublevels (levels) + "Hide everything but the top LEVELS levels of headers, in whole buffer." + (interactive "p") + (if (< levels 1) + (error "Must keep at least one level of headers")) + (let (outline-view-change-hook) + (save-excursion + (goto-char (point-min)) + ;; Skip the prelude, if any. + (unless (outline-on-heading-p t) (outline-next-heading)) + ;; First hide everything. + (outline-flag-region (point) (point-max) t) + ;; Then unhide the top level headers. + (outline-map-region + (lambda () + (if (<= (funcall outline-level) levels) + (outline-show-heading))) + (point) (point-max)))) + (run-hooks 'outline-view-change-hook)) + +(defun hide-other () + "Hide everything except current body and parent and top-level headings." + (interactive) + (hide-sublevels 1) + (let (outline-view-change-hook) + (save-excursion + (outline-back-to-heading t) + (show-entry) + (while (condition-case nil (progn (outline-up-heading 1 t) (not (bobp))) + (error nil)) + (outline-flag-region (max 1 (1- (point))) + (save-excursion (forward-line 1) (point)) + nil)))) + (run-hooks 'outline-view-change-hook)) + +(defun outline-toggle-children () + "Show or hide the current subtree depending on its current state." + (interactive) + (save-excursion + (outline-back-to-heading) + (if (not (outline-invisible-p (point-at-eol))) + (hide-subtree) + (show-children) + (show-entry)))) + +(defun outline-flag-subtree (flag) + (save-excursion + (outline-back-to-heading) + (outline-end-of-heading) + (outline-flag-region (point) + (progn (outline-end-of-subtree) (point)) + flag))) + +(defun outline-end-of-subtree () + (outline-back-to-heading) + (let ((first t) + (level (funcall outline-level))) + (while (and (not (eobp)) + (or first (> (funcall outline-level) level))) + (setq first nil) + (outline-next-heading)) + (if (bolp) + (progn + ;; Go to end of line before heading + (forward-char -1) + (if (and outline-blank-line (bolp)) + ;; leave blank line before heading + (forward-char -1)))))) + +(defun show-branches () + "Show all subheadings of this heading, but not their bodies." + (interactive) + (show-children 1000)) + +(defun show-children (&optional level) + "Show all direct subheadings of this heading. +Prefix arg LEVEL is how many levels below the current level should be shown. +Default is enough to cause the following heading to appear." + (interactive "P") + (setq level + (if level (prefix-numeric-value level) + (save-excursion + (outline-back-to-heading) + (let ((start-level (funcall outline-level))) + (outline-next-heading) + (if (eobp) + 1 + (max 1 (- (funcall outline-level) start-level))))))) + (let (outline-view-change-hook) + (save-excursion + (outline-back-to-heading) + (setq level (+ level (funcall outline-level))) + (outline-map-region + (lambda () + (if (<= (funcall outline-level) level) + (outline-show-heading))) + (point) + (progn (outline-end-of-subtree) + (if (eobp) (point-max) (1+ (point))))))) + (run-hooks 'outline-view-change-hook)) + + + +(defun outline-up-heading (arg &optional invisible-ok) + "Move to the visible heading line of which the present line is a subheading. +With argument, move up ARG levels. +If INVISIBLE-OK is non-nil, also consider invisible lines." + (interactive "p") + (and (eq this-command 'outline-up-heading) + (or (eq last-command 'outline-up-heading) (push-mark))) + (outline-back-to-heading invisible-ok) + (let ((start-level (funcall outline-level))) + (if (eq start-level 1) + (error "Already at top level of the outline")) + (while (and (> start-level 1) (> arg 0) (not (bobp))) + (let ((level start-level)) + (while (not (or (< level start-level) (bobp))) + (if invisible-ok + (outline-previous-heading) + (outline-previous-visible-heading 1)) + (setq level (funcall outline-level))) + (setq start-level level)) + (setq arg (- arg 1)))) + (looking-at outline-regexp)) + +(defun outline-forward-same-level (arg) + "Move forward to the ARG'th subheading at same level as this one. +Stop at the first and last subheadings of a superior heading." + (interactive "p") + (outline-back-to-heading) + (while (> arg 0) + (let ((point-to-move-to (save-excursion + (outline-get-next-sibling)))) + (if point-to-move-to + (progn + (goto-char point-to-move-to) + (setq arg (1- arg))) + (progn + (setq arg 0) + (error "No following same-level heading")))))) + +(defun outline-get-next-sibling () + "Move to next heading of the same level, and return point or nil if none." + (let ((level (funcall outline-level))) + (outline-next-visible-heading 1) + (while (and (not (eobp)) (> (funcall outline-level) level)) + (outline-next-visible-heading 1)) + (if (or (eobp) (< (funcall outline-level) level)) + nil + (point)))) + +(defun outline-backward-same-level (arg) + "Move backward to the ARG'th subheading at same level as this one. +Stop at the first and last subheadings of a superior heading." + (interactive "p") + (outline-back-to-heading) + (while (> arg 0) + (let ((point-to-move-to (save-excursion + (outline-get-last-sibling)))) + (if point-to-move-to + (progn + (goto-char point-to-move-to) + (setq arg (1- arg))) + (progn + (setq arg 0) + (error "No previous same-level heading")))))) + +(defun outline-get-last-sibling () + "Move to previous heading of the same level, and return point or nil if none." + (let ((level (funcall outline-level))) + (outline-previous-visible-heading 1) + (while (and (> (funcall outline-level) level) + (not (bobp))) + (outline-previous-visible-heading 1)) + (if (< (funcall outline-level) level) + nil + (point)))) + +(defun outline-headers-as-kill (beg end) + "Save the visible outline headers in region at the start of the kill ring. + +Text shown between the headers isn't copied. Two newlines are +inserted between saved headers. Yanking the result may be a +convenient way to make a table of contents of the buffer." + (interactive "r") + (save-excursion + (save-restriction + (narrow-to-region beg end) + (goto-char (point-min)) + (let ((buffer (current-buffer)) + start end) + (with-temp-buffer + (with-current-buffer buffer + ;; Boundary condition: starting on heading: + (when (outline-on-heading-p) + (outline-back-to-heading) + (setq start (point) + end (progn (outline-end-of-heading) + (point))) + (insert-buffer-substring buffer start end) + (insert "\n\n"))) + (let ((temp-buffer (current-buffer))) + (with-current-buffer buffer + (while (outline-next-heading) + (unless (outline-invisible-p) + (setq start (point) + end (progn (outline-end-of-heading) (point))) + (with-current-buffer temp-buffer + (insert-buffer-substring buffer start end) + (insert "\n\n")))))) + (kill-new (buffer-string))))))) + +(provide 'outline) +(provide 'noutline) + +;; arch-tag: 1724410e-7d4d-4f46-b801-49e18171e874 +;;; outline.el ends here diff --git a/xemacs/ps-print-invisible.el b/xemacs/ps-print-invisible.el new file mode 100644 index 0000000..8f005fe --- /dev/null +++ b/xemacs/ps-print-invisible.el @@ -0,0 +1,225 @@ +;;; ps-print-invisible.el - addon to ps-print package that deals +;; with invisible text printing in xemacs + +;; Author: Greg Chernov +;; +;; GNU Emacs is free software; you can redistribute it and/or modify +;; it under the terms of the GNU General Public License as published by +;; the Free Software Foundation; either version 2, or (at your option) +;; any later version. + +;; GNU Emacs is distributed in the hope that it will be useful, +;; but WITHOUT ANY WARRANTY; without even the implied warranty of +;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +;; GNU General Public License for more details. + +;; You should have received a copy of the GNU General Public License +;; along with GNU Emacs; see the file COPYING. If not, write to the +;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, +;; Boston, MA 02110-1301, USA. +;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; +;; +;;; Commentary: +;; +;; Put ps-print-invisible.el on your load path. +;; (require 'ps-print-invisible) +;; ps-print-buffer-with-faces will not print invisible parts of the buffer. +;; Work with invisible extents/text properties only +;; (xemacs hideshow and noutline packages). + +(defun ps-generate-postscript-with-faces (from to) + ;; Some initialization... + (setq ps-current-effect 0) + + ;; Build the reference lists of faces if necessary. + (when (or ps-always-build-face-reference + ps-build-face-reference) + (message "Collecting face information...") + (ps-build-reference-face-lists)) + + ;; Black/white printer. + (setq ps-black-white-faces-alist nil) + (and (eq ps-print-color-p 'black-white) + (ps-extend-face-list ps-black-white-faces nil + 'ps-black-white-faces-alist)) + + ;; Generate some PostScript. + (save-restriction + (narrow-to-region from to) + (ps-print-ensure-fontified from to) + (let ((face 'default) + (position to)) + (cond + ((memq ps-print-emacs-type '(xemacs lucid)) + ;; Build the list of extents... + ;;(debug) + (let ((a (cons 'dummy nil)) + record type extent extent-list + (list-invisible (ps-print-find-invisible-xmas from to))) + (ps-x-map-extents 'ps-mapper nil from to a) + (setq a (sort (cdr a) 'car-less-than-car) + extent-list nil) + + ;; Loop through the extents... + (while a + (setq record (car a) + position (car record) + + record (cdr record) + type (car record) + + record (cdr record) + extent (car record)) + + ;; Plot up to this record. + ;; XEmacs 19.12: for some reason, we're getting into a + ;; situation in which some of the records have + ;; positions less than 'from'. Since we've narrowed + ;; the buffer, this'll generate errors. This is a hack, + ;; but don't call ps-plot-with-face unless from > point-min. + (and (>= from (point-min)) + (ps-plot-with-face from (min position (point-max)) face)) + + (cond + ((eq type 'push) + (and (or (ps-x-extent-face extent) + (extent-property extent 'invisible)) + (setq extent-list (sort (cons extent extent-list) + 'ps-extent-sorter)))) + + ((eq type 'pull) + (setq extent-list (sort (delq extent extent-list) + 'ps-extent-sorter)))) + + + (setq face (if extent-list + (let ((prop (extent-property (car extent-list) 'invisible))) + (if (or (and (eq buffer-invisibility-spec t) + (not (null prop))) + (and (consp buffer-invisibility-spec) + (or (memq prop buffer-invisibility-spec) + (assq prop buffer-invisibility-spec)))) + 'emacs--invisible--face + (ps-x-extent-face (car extent-list)))) + 'default) + from position + a (cdr a))))) + + ((eq ps-print-emacs-type 'emacs) + (let ((property-change from) + (overlay-change from) + (save-buffer-invisibility-spec buffer-invisibility-spec) + (buffer-invisibility-spec nil) + before-string after-string) + (while (< from to) + (and (< property-change to) ; Don't search for property change + ; unless previous search succeeded. + (setq property-change (next-property-change from nil to))) + (and (< overlay-change to) ; Don't search for overlay change + ; unless previous search succeeded. + (setq overlay-change (min (ps-e-next-overlay-change from) + to))) + (setq position (min property-change overlay-change) + before-string nil + after-string nil) + ;; The code below is not quite correct, + ;; because a non-nil overlay invisible property + ;; which is inactive according to the current value + ;; of buffer-invisibility-spec nonetheless overrides + ;; a face text property. + (setq face + (cond ((let ((prop (get-text-property from 'invisible))) + ;; Decide whether this invisible property + ;; really makes the text invisible. + (if (eq save-buffer-invisibility-spec t) + (not (null prop)) + (or (memq prop save-buffer-invisibility-spec) + (assq prop save-buffer-invisibility-spec)))) + 'emacs--invisible--face) + ((get-text-property from 'face)) + (t 'default))) + (let ((overlays (ps-e-overlays-at from)) + (face-priority -1)) ; text-property + (while (and overlays + (not (eq face 'emacs--invisible--face))) + (let* ((overlay (car overlays)) + (overlay-invisible + (ps-e-overlay-get overlay 'invisible)) + (overlay-priority + (or (ps-e-overlay-get overlay 'priority) 0))) + (and (> overlay-priority face-priority) + (setq before-string + (or (ps-e-overlay-get overlay 'before-string) + before-string) + after-string + (or (and (<= (ps-e-overlay-end overlay) position) + (ps-e-overlay-get overlay 'after-string)) + after-string) + face-priority overlay-priority + face + (cond + ((if (eq save-buffer-invisibility-spec t) + (not (null overlay-invisible)) + (or (memq overlay-invisible + save-buffer-invisibility-spec) + (assq overlay-invisible + save-buffer-invisibility-spec))) + 'emacs--invisible--face) + ((ps-e-overlay-get overlay 'face)) + (t face) + )))) + (setq overlays (cdr overlays)))) + ;; Plot up to this record. + (and before-string + (ps-plot-string before-string)) + (ps-plot-with-face from position face) + (and after-string + (ps-plot-string after-string)) + (setq from position))))) + (ps-plot-with-face from to face)))) + + +(defun ps-print-find-invisible-xmas (from to) + (let ((list nil)) + (map-extents '(lambda (ex ignored) + (let ((prop (extent-property ex 'invisible))) + (if (or (and (eq buffer-invisibility-spec t) + (not (null prop))) + (or (memq prop buffer-invisibility-spec) + (assq prop buffer-invisibility-spec))) + (setq list (cons (list + (extent-start-position ex) + (extent-end-position ex)) + list)))) + nil) + (current-buffer) + from to nil 'start-and-end-in-region 'invisible) + (reverse list))) + + +(defun ps-mapper (extent list) + ;;(debug) + (let ((beg (ps-x-extent-start-position extent)) + (end (ps-x-extent-end-position extent)) + (inv-lst list-invisible) + (found nil)) + (while (and inv-lst + (not found)) + (let ((inv-beg (caar inv-lst)) + (inv-end (cadar inv-lst))) + (if (and (>= beg inv-beg) + (<= end inv-end) + (not (extent-property extent 'invisible))) + (setq found t)) + (setq inv-lst (cdr inv-lst)))) + (if (not found) + (nconc list + (list (list beg 'push extent) + (list end 'pull extent))))) + nil) + + +(provide 'ps-print-invisible) + + +;;; ps-print-invisible.el ends here
\ No newline at end of file |