diff options
| author | Carsten Dominik <dominik@nb-dominik2.science.uva.nl> | 2008-01-31 11:31:37 +0100 |
|---|---|---|
| committer | Carsten Dominik <dominik@nb-dominik2.science.uva.nl> | 2008-01-31 11:31:37 +0100 |
| commit | 9b9f2f607084dce8f656aa75c9731e6a644b20ea (patch) | |
| tree | ef622984442b3553863779ff9108f02c34d28639 | |
| parent | fcf5c84bc830c4a13996263f042148f9c7bf1ad3 (diff) | |
| download | org-mode-9b9f2f607084dce8f656aa75c9731e6a644b20ea.tar.gz | |
Release 4.30release_4.30
| -rw-r--r-- | org | 987 | ||||
| -rw-r--r-- | org-install.el | 27 | ||||
| -rw-r--r-- | org-publish.el | 561 | ||||
| -rw-r--r-- | org.el | 505 | ||||
| -rw-r--r-- | org.pdf | bin | 482382 -> 514310 bytes | |||
| -rw-r--r-- | org.texi | 636 | ||||
| -rw-r--r-- | orgcard.pdf | bin | 58476 -> 58097 bytes | |||
| -rw-r--r-- | orgcard.tex | 90 |
8 files changed, 2270 insertions, 536 deletions
@@ -5,7 +5,7 @@ START-INFO-DIR-ENTRY * Org Mode: (org). outline-based notes management and organizer END-INFO-DIR-ENTRY - This manual is for Org-mode (version 4.29). + This manual is for Org-mode (version 4.30). 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.29). +This manual is for Org-mode (version 4.30). Copyright (C) 2004, 2005, 2006 Free Software Foundation @@ -54,6 +54,7 @@ This manual is for Org-mode (version 4.29). * Tags:: Tagging headlines and matching sets of tags * Agenda views:: Collecting information into views * Exporting:: Sharing and publishing of notes +* Publishing:: * Miscellaneous:: All the rest which did not fit elsewhere * Index:: The fast road to specific information * Key Index:: Key bindings and where they are described @@ -155,7 +156,7 @@ Exporting * ASCII export:: Exporting to plain ASCII * HTML export:: Exporting to HTML -* XML export:: Exporting to XML +* XOXO export:: Exporting to XOXO * iCalendar export:: Exporting in iCalendar format * Text interpretation:: How the exporter looks at the file @@ -165,6 +166,27 @@ Text interpretation by the exporter * Enhancing text:: Subscripts, symbols and more * Export options:: How to influence the export settings +Publishing + +* Configuration:: Defining projects +* Sample configuration:: Example projects +* Triggering publication:: Publication commands + +Configuration + +* Project alist:: The central configuration variable +* File sources and destinations:: From here to there +* Selecting files:: What files are part of the project? +* Publishing action:: +* Publishing options:: Tweaking HTML export +* Links:: Linking between files of a project +* Project page index:: Publishing a list of project files + +Sample configuration + +* Simple example:: One-component publishing +* Complex example:: A multi-component publishing example + Miscellaneous * Completion:: M-TAB knows what you need @@ -178,6 +200,12 @@ Miscellaneous * 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 + File: org, Node: Introduction, Next: Document structure, Prev: Top, Up: Top @@ -211,20 +239,22 @@ the Emacs calendar and diary. Plain text URL-like links connect to websites, emails, Usenet messages, BBDB entries, and any files related to the projects. For printing and sharing of notes, an Org-mode file can be exported as a structured ASCII file, as HTML, or (todo and -agenda items only) as an iCalendar file. +agenda items only) as an iCalendar file. It can also serve as a +publishing tool for a set of linked webpages. Org-mode keeps simple things simple. When first fired up, it should -feel like a simple, easy to use outliner. Complexity is not imposed, -but a large amount of functionality is available when you need it. -Org-mode can be used on different levels and in different ways, for +feel like a straightforward, easy to use outliner. Complexity is not +imposed, but a large amount of functionality is available when you need +it. Org-mode can be used on different levels and in different ways, for example: * as an outline extension with visibility cycling and structure editing * as an ASCII system and table editor for taking structured notes * as an ASCII table editor with spreadsheet-like capabilities - * as a simple hypertext system, with HTML export * as a TODO list editor * as a full agenda and planner with deadlines and work scheduling + * as a simple hypertext system, with HTML export + * as a publishing tool to create a set of interlinked webpages The Org-mode table editor can be integrated into any major mode by activating the minor Orgtbl-mode. @@ -250,17 +280,19 @@ two lines define _global_ keys for the commands `org-store-link' and (define-key global-map "\C-cl" 'org-store-link) (define-key global-map "\C-ca" 'org-agenda) - If you have downloaded Org-mode from the Web, you must byte-compile -`org.el' and put it on your load path. In addition to the Emacs Lisp -lines above, you also need to add the following lines to `.emacs': + Furthermore, you must activate `font-lock-mode' in org-mode buffers, +because significant functionality depends on font-locking being active. +You can do this with either one of the following two lines: + (global-font-lock-mode 1) ; for all buffers + (add-hook 'org-mode-hook 'turn-on-font-lock) ; org-mode buffers only + + If you have downloaded Org-mode from the Web, you must take +additional action: Byte-compile `org.el' and `org-publish.el' and put +them together with `org-install.el' on your load path. Then add to +`.emacs': - ;; These lines only if org-mode is not part of the X/Emacs distribution. - (autoload 'org-mode "org" "Org mode" t) - (autoload 'org-diary "org" "Diary entries from Org mode") - (autoload 'org-agenda "org" "Multi-file agenda from Org mode" t) - (autoload 'org-store-link "org" "Store a link to the current location" t) - (autoload 'orgtbl-mode "org" "Org tables as a minor mode" t) - (autoload 'turn-on-orgtbl "org" "Org tables as a minor mode") + ;; This line only if org-mode is not part of the X/Emacs distribution. + (require 'org-install) 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 @@ -358,20 +390,24 @@ File: org, Node: Visibility cycling, Next: Motion, Prev: Headlines, Up: Docu ====================== Outlines make it possible to hide parts of the text in the buffer. -Org-mode uses a single command bound to the <TAB> key to change the -visibility in the buffer. +Org-mode uses just two commands, bound to <TAB> and `S-<TAB>' to change +the visibility in the buffer. `<TAB>' - Rotate current subtree between the states + _Subtree cycling_: Rotate current subtree between the states ,-> FOLDED -> CHILDREN -> SUBTREE --. '-----------------------------------' - At the beginning of the buffer (or when called with `C-u'), this - does the same as the command `S-<TAB>' below. + The cursor must be on a headline for this to work(1). When the + cursor is at the beginning of the buffer and the first line is not + a headline, then <TAB> actually runs global cycling (see + below)(2). Also when called with a prefix argument (`C-u <TAB>'), + global cycling is invoked. `S-<TAB>' - Rotate the entire buffer between the states +`C-u <TAB>' + _Global cycling_: Rotate the entire buffer between the states ,-> OVERVIEW -> CONTENTS -> SHOW ALL --. '--------------------------------------' @@ -390,6 +426,12 @@ basis by adding one of the following lines anywhere in the buffer: #+STARTUP: content #+STARTUP: showall + ---------- Footnotes ---------- + + (1) see, however, the option `org-cycle-emulate-tab'. + + (2) see the option `org-cycle-global-at-bob'. + File: org, Node: Motion, Next: Structure editing, Prev: Visibility cycling, Up: Document structure @@ -586,9 +628,19 @@ is indented like the bullet/number, or less. For example: But in the end, not individual scenes matter but the film as a whole. Org-mode supports these lists by tuning filling and wrapping commands -to correctly deal with them. Furthermore, the following commands act -on items when the cursor is in the first line of an item (the line with -the bullet or number). +to correctly deal with them. + + Every item in a plain list can be made a checkbox by starting it with +the string `[_]'. The checkbox status can conveniently be toggled with +`C-c C-c'. + + * Shopping list + - [_] Milk + - [X] Butter + - [_] bred + + The following commands act on items when the cursor is in the first +line of an item (the line with the bullet or number). `<TAB>' Items can be folded just like headline levels if you set the @@ -605,7 +657,8 @@ the bullet or number). _whitespace before a bullet or number_, the new item is created _before_ the current item. If the command is executed in the white space before the text that is part of an item but does not - contain the bullet, a bullet is added to the current line. + contain the bullet, a bullet is added to the current line. If the + current item has a checkbox, so will the newly created item. `M-S-<up>' `M-S-<down>' @@ -623,7 +676,9 @@ the bullet or number). hierarchy, break the command chain with a cursor motion or so. `C-c C-c' - Renumber the ordered list at the cursor. + If there is a checkbox in the item line, toggle the state of the + checkbox. Otherwise, if this is an ordered list, renumber the + ordered list at the cursor. ---------- Footnotes ---------- @@ -828,7 +883,7 @@ Calculations along with it. Depending on the variable `org-table-copy-increment', integer field values will be incremented during copy. This key is also used by CUA-mode (*note - Interaction::). + Cooperation::). Miscellaneous ............. @@ -1242,7 +1297,7 @@ File: org, Node: Hyperlinks, Next: TODO items, Prev: Tables, Up: Top 4 Hyperlinks ************ -Just like HMTL, Org-mode provides links inside a file, and external +Just like HTML, Org-mode provides links inside a file, and external links to other files, Usenet articles, emails and much more. * Menu: @@ -1437,6 +1492,10 @@ insert it into an org-mode file, and to follow the link. text, and you can type or paste them straight into the buffer. By using this command, the links are automatically enclosed in double brackets, and you will be asked for the optional descriptive text. + If the link is a `file:' link and the linked file is located in + the same directory as the current file or a subdirectory of it, the + path of the file will be inserted relative to the current + directory. `C-u C-c C-l' When `C-c C-l' is called with a `C-u' prefix argument, a link to a @@ -1570,15 +1629,12 @@ quick notes with little interruption of your work flow. See information. The notes produced by _Remember_ can be stored in different ways, and Org-mode files are a good target. Org-mode allows to file away notes either to a default file, or directly to the correct -location in your Org-mode outline tree. The following customization(1) +location in your Org-mode outline tree. The following customization will tell _Remember_ to use org files as target, and to create annotations compatible with Org-mode links. (setq org-directory "~/path/to/my/orgfiles/") (setq org-default-notes-file "~/.notes") - (autoload 'org-remember-annotation "org") - (autoload 'org-remember-apply-template "org") - (autoload 'org-remember-handler "org") (setq remember-annotation-functions '(org-remember-annotation)) (setq remember-handler-functions '(org-remember-handler)) (add-hook 'remember-mode-hook 'org-remember-apply-template) @@ -1641,11 +1697,6 @@ data. If the variable `org-adapt-indentation' is non-nil, the entire text is also indented so that it starts in the same column as the headline (after the asterisks). - ---------- Footnotes ---------- - - (1) The three autoload forms are only necessary if `org.el' is not -part of the Emacs distribution or an XEmacs package. - File: org, Node: TODO items, Next: Timestamps, Prev: Hyperlinks, Up: Top @@ -1875,7 +1926,7 @@ agenda (*note Weekly/Daily agenda::). Increase/decrease priority of current item. Note that these keys are also used to modify time stamps (*note Creating timestamps::). Furthermore, these keys are also used by CUA-mode (*note - Interaction::). + Conflicts::). File: org, Node: Timestamps, Next: Tags, Prev: TODO items, Up: Top @@ -1998,7 +2049,7 @@ format. `S-<left>' `S-<right>' Change date at cursor by one day. These key bindings conflict with - CUA-mode (*note Interaction::). + CUA-mode (*note Conflicts::). `S-<up>' `S-<down>' @@ -2006,7 +2057,7 @@ format. be on a year, month, day, hour or minute. Note that if the cursor is not at a time stamp, these same keys modify the priority of an item. (*note Priorities::). The key bindings also conflict with - CUA-mode (*note Interaction::). + CUA-mode (*note Conflicts::). `C-c C-y' Evaluate a time range by computing the difference between start and @@ -2689,7 +2740,7 @@ Quit and Exit -File: org, Node: Exporting, Next: Miscellaneous, Prev: Agenda views, Up: Top +File: org, Node: Exporting, Next: Publishing, Prev: Agenda views, Up: Top 9 Exporting *********** @@ -2697,7 +2748,7 @@ File: org, Node: Exporting, Next: Miscellaneous, Prev: Agenda views, Up: Top Org-mode documents can be exported into a variety of other formats. For printing and sharing of notes, ASCII export produces a readable and simple version of an Org-mode file. HTML export allows to publish a -notes file on the web, while the XML format provides a solid base for +notes file on the web, while the XOXO format provides a solid base for exchange with a broad range of other applications. To incorporate entries with associated times like deadlines or appointments into a desktop calendar program like iCal, Org-mode can also produce extracts @@ -2711,7 +2762,7 @@ output produced. *Note Text interpretation::, for more details. * ASCII export:: Exporting to plain ASCII * HTML export:: Exporting to HTML -* XML export:: Exporting to XML +* XOXO export:: Exporting to XOXO * iCalendar export:: Exporting in iCalendar format * Text interpretation:: How the exporter looks at the file @@ -2744,7 +2795,7 @@ example, creates only top level headlines and does the rest as items. -File: org, Node: HTML export, Next: XML export, Prev: ASCII export, Up: Exporting +File: org, Node: HTML export, Next: XOXO export, Prev: ASCII export, Up: Exporting 9.2 HTML export =============== @@ -2778,8 +2829,17 @@ creates two levels of headings and does the rest as items. mark them with a `@' like in `@<b>bold text@</b>'. Plain `<' and `>' are always transformed to `<' and `>' in HTML export. - You can also give style information for the exported file. The -default specification can be configured through the option + You can also give style information for the exported file. The HTML +exporter asigns the following CSS classes to appropriate parts of the +document - your style specifications may change these. + .todo TODO keywords + .done the DONE keyword + .timestamp time stamp + .timestamp-kwd keyword associated with a time stamp, like SCHEDULED + .tag tag in a headline + .target target for links + + The default specification can be configured through the option `org-export-html-style'. If you want to use a file-local style, you may use file variables, best wrapped into a COMMENT section at the end of the outline tree. For example: @@ -2799,23 +2859,23 @@ current buffer and forces Emacs to re-evaluate the local variables section in the buffer. -File: org, Node: XML export, Next: iCalendar export, Prev: HTML export, Up: Exporting +File: org, Node: XOXO export, Next: iCalendar export, Prev: HTML export, Up: Exporting -9.3 XML export -============== +9.3 XOXO export +=============== -Org-mode contains an XML exporter that produces XOXO-style XML. +Org-mode contains an exporter that produces XOXO-style output. Currently, this exporter only handles the general outline structure and does not interpret any additional Org-mode features. `C-c C-x C-x' - Export as XML file `myfile.xml'. + Export as XOXO file `myfile.html'. `C-c C-x v x' Export only the visible part of the document. -File: org, Node: iCalendar export, Next: Text interpretation, Prev: XML export, Up: Exporting +File: org, Node: iCalendar export, Next: Text interpretation, Prev: XOXO export, Up: Exporting 9.4 iCalendar export ==================== @@ -2968,9 +3028,325 @@ you can: TeX: turn on/off TeX macros -File: org, Node: Miscellaneous, Next: Index, Prev: Exporting, Up: Top +File: org, Node: Publishing, Next: Miscellaneous, Prev: Exporting, Up: Top + +10 Publishing +************* + +Org-mode includes(1) a publishing management system that allows you to +configure automatic html conversion of _projects_ composed of +interlinked org files. This system is called _org-publish_. You can +also configure org-publish to automatically upload your exported HTML +pages and related attachments, such as images and source code files, to +a web server. Org-publish turns org-mode into a web-site authoring +tool. + + Org-publish has been contributed to Org-mode by David O'Toole. + +* Menu: + +* Configuration:: Defining projects +* Sample configuration:: Example projects +* Triggering publication:: Publication commands + + ---------- Footnotes ---------- + + (1) `org-publish.el' is not yet part of emacs, so if you are using +`org.el' as it comes with Emacs, you need to download this file +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 +================== + +Publishing needs significant configuration to specify files, destination +and many other properties of a project. + +* Menu: + +* Project alist:: The central configuration variable +* File sources and destinations:: From here to there +* Selecting files:: What files are part of the project? +* Publishing action:: +* Publishing options:: Tweaking HTML export +* Links:: Linking between files 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 + +10.1.1 The variable `org-publish-project-alist' +----------------------------------------------- + +Org-publish is configured almost entirely through setting the value of +one variable, called `org-publish-project-alist'. Each element of the +list configures one project, and may be in one of the two following +forms: + + ("project-name" :property value :property value ...) + + or + + ("project-name" + ("component1" :property value :property value ...) + ("component2" :property value :property value ...) + ...) + + In both cases, projects are configured by specifying property values. +A project defines the set of files that will be published, as well as +the publishing configuration to use when publishing those files. When +a project takes the second form listed above, the individual property +lists are taken to be "components" of the project, which group together +files requiring different publishing options. + + +File: org, Node: File sources and destinations, Next: Selecting files, Prev: Project alist, Up: Configuration + +10.1.2 Sources and destinations for files +----------------------------------------- + +Most properties are optional, but some should always be set. In +particular, org-publish needs to know where to look for source files, +and where to put published files. + +`:base-directory' Directory containing publishing source files +`:publishing-directory'Directory (possibly remote) where output files + will be published. + + +File: org, Node: Selecting files, Next: Publishing action, Prev: File sources and destinations, Up: Configuration + +10.1.3 Selecting files +---------------------- + +By default, all files with extension `.org' in the base directory are +considered part of the project. This can be modified by setting the +properties +`:base-extension' Extension (without the dot!) of source files. This + actually is a regular expression. +`:exclude' Regular expression to match file names that should + not be published, even though they have been selected + on the basis of their extension. +`:include' List of files to be included regardless of + `:base-extension' and `:exclude'. + + +File: org, Node: Publishing action, Next: Publishing options, Prev: Selecting files, Up: Configuration + +10.1.4 Publishing Action +------------------------ + +Publishing means that a file is copied to the destination directory and +possibly transformed in the process. The default transformation is to +export Org-mode files as HTML files, and this is done by the function +`org-publish-org-to-html' which calls the HTML exporter (*note HTML +export::). Other files like images only need to be copied to the +publishing destination. For non-Org-mode files, you need to specify +the publishing function. + +`:publishing-function' Function executing the publication of a file. + + The function must accept two arguments: a property list containing at +least a `:publishing-directory' property, and the name of the file to +be published. I should take the specified file, make the necessary +transformation (if any) and place the result into the destination +folder. You can write your own publishing function, but `org-publish' +provides one for attachments (files that only need to be copied): +`org-publish-attachment'. + + +File: org, Node: Publishing options, Next: Links, Prev: Publishing action, Up: Configuration + +10.1.5 Options for the HTML exporter +------------------------------------ + +The property list can be used to set many export options for the HTML +exporter. In most cases, these properties correspond to user variables +in Org-mode. The table below lists these properties along with the +variable they belong to. See the documentation string for the +respective variable for details. + +`:language' `org-export-default-language' +`:headline-levels' `org-export-headline-levels' +`:section-numbers' `org-export-with-section-numbers' +`:table-of-contents' `org-export-with-toc' +`:emphasize' `org-export-with-emphasize' +`:sub-superscript' `org-export-with-sub-superscripts' +`:TeX-macros' `org-export-with-TeX-macros' +`:fixed-width' `org-export-with-fixed-width' +`:timestamps' `org-export-with-timestamps' + . +`:tags' `org-export-with-tags' + . +`:tables' `org-export-with-tables' +`:table-auto-headline' `org-export-highlight-first-table-line' +`:style' `org-export-html-style' +`:convert-org-links' `org-export-html-link-org-files-as-html' +`:inline-images' `org-export-html-inline-images' +`:expand-quoted-html' `org-export-html-expand' +`:timestamp' `org-export-html-with-timestamp' +`:publishing-directory'`org-export-publishing-directory' +`:preamble' `org-export-html-preamble' +`:postamble' `org-export-html-postamble' +`:auto-preamble' `org-export-html-auto-preamble' +`:auto-postamble' `org-export-html-auto-postamble' +`:author' `user-full-name' +`:email' `user-mail-address' + + When a property is given a value in org-publish-project-alist, its +setting overrides the value of the corresponding user variable (if any) +during publishing. However, options set within a file (*note Export +options::) override everything. + + +File: org, Node: Links, Next: Project page index, Prev: Publishing options, Up: Configuration + +10.1.6 Links between published files +------------------------------------ + +To create a link from one Org-mode file to another, you would use +something like `[[file:foo.org][The foo]]' or simply `file:foo.org.' +(*note Hyperlinks::). Upon publishing this link becomes a link to +`foo.html'. In this way, you can interlink the pages of your "org web" +project and the links will work as expected when you publish them to +HTML. + + You may also link to related files, such as images. Provided you are +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. + + +File: org, Node: Project page index, Prev: Links, Up: Configuration + +10.1.7 Project page index +------------------------- + +The following properties may be used to control publishing of an index +of files or summary page for a given project. + +`:auto-index' When non-nil, 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 generates + a plain list of links to all files in the project. + + +File: org, Node: Sample configuration, Next: Triggering publication, Prev: Configuration, Up: Publishing + +10.2 Sample configuration +========================= + +Below we provide two example configurations. The first one is a simple +project publishing only a set of Org-mode files. The second example is +more complex, with a multi-component project. + +* Menu: + +* Simple example:: One-component publishing +* Complex example:: A multi-component publishing example + + +File: org, Node: Simple example, Next: Complex example, Prev: Sample configuration, Up: Sample configuration + +10.2.1 Example: simple publishing configuration +----------------------------------------------- + +This example publishes a set of Org-mode files to the `public_html' +directory on the local machine. + + (setq org-publish-project-alist + '(("org" + :base-directory "~/org/" + :publishing-directory "~/public_html" + :section-numbers nil + :table-of-contents nil + :style "<link rel=stylesheet + href=\"../other/mystyle.css\" + type=\"text/css\">"))) + + +File: org, Node: Complex example, Prev: Simple example, Up: Sample configuration + +10.2.2 Example: complex publishing configuration +------------------------------------------------ + +This more complicated example publishes an entire website, including +org files converted to HTML, image files, emacs lisp source code, and +stylesheets. The publishing-directory is remote and private files are +excluded. + + To ensure that links are preserved, care should be taken to replicate +your directory structure on the web server, and to use relative file +paths. For example, if your org files are kept in `~/org' and your +publishable images in `~/images', you'd link to an image with + file:../images/myimage.png + On the web server, the relative path to the image should be the +same. You can accomplish this by setting up an "images" folder in the +right place on the webserver, and publishing images to it. + + (setq org-publish-project-alist + '(("website" + ("orgfiles" + :base-directory "~/org/" + :base-extension "org" + :publishing-directory "/ssh:user@host:~/html/notebook/" + :publishing-function org-publish-org-to-html + :exclude "PrivatePage.org" ;; regexp + :headline-levels 3 + :section-numbers nil + :table-of-contents nil + :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\\|el" + :publishing-directory "/ssh:user@host:~/html/other/" + :publishing-function org-publish-attachment)))) + + +File: org, Node: Triggering publication, Prev: Sample configuration, Up: Publishing + +10.3 Triggering publication +=========================== + +Once org-publish is properly configured, you can publish with the +following functions: + +`C-c C-e c' + Prompts for a specific project to publish. + +`C-c C-e p' + Publishes the project the current file is part of. + +`C-c C-e f' + Publishes only the current file. + +`C-c C-e a' + Publish all projects. + + 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. + + +File: org, Node: Miscellaneous, Next: Index, Prev: Publishing, Up: Top -10 Miscellaneous +11 Miscellaneous **************** * Menu: @@ -2989,7 +3365,7 @@ File: org, Node: Miscellaneous, Next: Index, Prev: Exporting, Up: Top File: org, Node: Completion, Next: Customization, Prev: Miscellaneous, Up: Miscellaneous -10.1 Completion +11.1 Completion =============== Org-mode supports in-buffer completion. This type of completion does @@ -3017,7 +3393,7 @@ buffer and use the key to complete text right there. File: org, Node: Customization, Next: Summary of in-buffer settings, Prev: Completion, Up: Miscellaneous -10.2 Customization +11.2 Customization ================== There are more than 100 variables that can be used to customize @@ -3031,7 +3407,7 @@ activated on a per-file basis, by putting special lines into the buffer File: org, Node: Summary of in-buffer settings, Next: The very busy C-c C-c key, Prev: Customization, Up: Miscellaneous -10.3 Summary of in-buffer settings +11.3 Summary of in-buffer settings ================================== Org-mode uses special lines in the buffer to define settings on a @@ -3060,6 +3436,10 @@ file is visited again in a new Emacs session. default value `nil'. align align all tables noalign don't align tables on startup + Logging when a TODO item is marked DONE (variable `org-log-done') + can be configured using these options. + logging record a timestamp when an item is marked DONE + nologging don't record when items are marked DONE Here are the options for hiding leading stars in outline headings. The corresponding variables are `org-hide-leading-stars' and `org-odd-levels-only', both with a default setting `nil' (meaning @@ -3090,7 +3470,7 @@ file is visited again in a new Emacs session. File: org, Node: The very busy C-c C-c key, Next: Clean view, Prev: Summary of in-buffer settings, Up: Miscellaneous -10.4 The very busy C-c C-c key +11.4 The very busy C-c C-c key ============================== The key `C-c C-c' has many purposes in org-mode, which are all @@ -3100,14 +3480,14 @@ circumstances it means something like _Hey Org-mode, look here and update according to what you see here_. Here is a summary what this means in different contexts. - - If the cursor is in one of the special #+KEYWORD lines, this + - If the cursor is in one of the special `#+KEYWORD' lines, this triggers scanning the buffer for these lines and updating the information. - If the cursor is inside a table, realign the table. This command works even if the automatic table editor has been turned off. - - If the cursor is on a #+TBLFM line, re-apply the formulas to the + - If the cursor is on a `#+TBLFM' line, re-apply the formulas to the entire table. - If the cursor is inside a table created by the `table.el' package, @@ -3117,16 +3497,19 @@ means in different contexts. with a prefix argument, file it without further interaction to the default location. - - If the cursor is on a <<<target>>>, update radio targets and + - If the cursor is on a `<<<target>>>', update radio targets and corresponding links in this buffer. + - If the cursor is in a plain list item with a checkbox, toggle the + status of the checkbox. + - If the cursor is on a numbered item in a plain list, renumber the ordered list. File: org, Node: Clean view, Next: TTY keys, Prev: The very busy C-c C-c key, Up: Miscellaneous -10.5 A cleaner outline view +11.5 A cleaner outline view =========================== Some people find it noisy and distracting that the Org-mode headlines @@ -3208,7 +3591,7 @@ org-convert-to-oddeven-levels'. File: org, Node: TTY keys, Next: FAQ, Prev: Clean view, Up: Miscellaneous -10.6 Using org-mode on a tty +11.6 Using org-mode on a tty ============================ Org-mode uses a number of keys that are not accessible on a tty. This @@ -3250,18 +3633,13 @@ Default Alternative 1 Alternative 2 File: org, Node: FAQ, Next: Interaction, Prev: TTY keys, Up: Miscellaneous -10.7 Frequently asked questions +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' - package which pretends to be also the standard outline-mode but is - not. This happens with older versions of `allout.el', for example - the one distributed with Emacs 21. Upgrade to Emacs 22 and this - problem will disappear. If for some reason you cannot do this, - make sure that org.el is loaded _before_ `allout.el', for example - by putting `(require 'org)' early enough into your `.emacs' file. + 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 @@ -3269,21 +3647,48 @@ File: org, Node: FAQ, Next: Interaction, Prev: TTY keys, Up: Miscellaneous (add-to-list 'auto-mode-alist '("README$" . org-mode)) - 3. Some of my links stopped working after I upgraded to a version + 3. I would like to use editing features of org-mode in other modes, + is his 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]]'. - 4. I see that Org-mode now creates links using the double bracket + 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. - 5. I don't care if you find the new bracket links great, I am + 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! @@ -3292,8 +3697,8 @@ File: org, Node: FAQ, Next: Interaction, Prev: TTY keys, Up: Miscellaneous (setq org-link-style 'plain org-link-format "<%s>") - 6. When I am executing shell links I always get a confirmation prompt - and need to type `yes <RET>', thats 4 key presses! Can I get rid + 8. When I am executing shell 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 @@ -3305,19 +3710,19 @@ File: org, Node: FAQ, Next: Interaction, Prev: TTY keys, Up: Miscellaneous shell links. It is also possible to turn off this check entirely, but I do not recommend to do this. Be warned. - 7. All these stars are driving me mad, I just find the Emacs outlines + 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::. - 8. I would like to have two windows on the same Org-mode file, but + 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. - 9. When I export my TODO list, every TODO item becomes a separate + 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 @@ -3335,43 +3740,41 @@ File: org, Node: FAQ, Next: Interaction, Prev: TTY keys, Up: Miscellaneous +OPTIONS: H:2; ... - 10. I would like to export only a subtree of my file to HTML. How? + 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. - 11. Org-mode takes over the S-cursor keys. I also want to use + 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 Interaction::. + Yes, see *Note Conflicts::. - 12. One of my table columns has started to fill up with `#ERROR'. + 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! - 13. When I am in the last column of a table and just above a + 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'. - 14. How can I change the indentation of an entire table without fixing + 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>. - 15. Is it possible to include entries from org-mode files into my + 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. The following steps are - necessary: Autoload the function `org-diary' as shown above under - *Note Installation and activation::. You also need to use _fancy - diary display_ by setting in `.emacs': + 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) @@ -3398,22 +3801,56 @@ File: org, Node: FAQ, Next: Interaction, Prev: TTY keys, Up: Miscellaneous File: org, Node: Interaction, Next: Bugs, Prev: FAQ, Up: Miscellaneous -10.8 Interaction with other packages +11.8 Interaction with other packages ==================================== -Org-mode can cooperate with the following packages: +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 + + +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-checklet.el' by Frank Ruell + Provides checklist of items which can be either checked or + unchecked. This is similar to the TODO functionality in Org-mode, + but never shows up in the agenda. `org-checklet' is freely + available at + `http://www.emacswiki.org/cgi-bin/emacs/org-checklet.el'. `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. Use a search engine to find this - package on the web. + context of a mouse-click. `org-mouse.el' is freely avaliable 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. However, + it is not yet part of Emacs 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'. -`table.el' by Takaaki Ota - Org mode cooperates with table.el, see *Note table.el::. - `table.el' is part of Emacs 22. + +File: org, Node: Cooperation, Next: Conflicts, Prev: Extensions, Up: Interaction + +11.8.2 Packages that Org-mode cooperates with +--------------------------------------------- `calc.el' by Dave Gillespie Org-mode uses the calc package for implementing spreadsheet @@ -3435,7 +3872,30 @@ Org-mode can cooperate with the following packages: at `http://www.astro.uva.nl/~dominik/Tools'. Org-mode checks for the function `constants-get', which has to be autoloaded in your setup. See the installation instructions in the file - `constants.el'. + `constants.el'. + +`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. + +`table.el' by Takaaki Ota + Org mode cooperates with table.el, see *Note table.el::. + `table.el' is part of Emacs 22. + + +File: org, Node: Conflicts, Prev: Cooperation, Up: Interaction + +11.8.3 Packages that lead to conflicts with Org-mode +---------------------------------------------------- + +`allout.el' by Ken Manheimer + Startup of Org-mode may fail with the error message + `(wrong-type-argument keymapp nil)' when there is an outdated + version `allout.el' on the load path, for example the version + distributed with Emacs 21.x. Upgrade to Emacs 22 and this problem + will disappear. If for some reason you cannot do this, make sure + that org.el is loaded _before_ `allout.el', for example by putting + `(require 'org)' early enough into your `.emacs' file. `CUA.el' by Kim. F. Storm Keybindings in Org-mode conflict with the `S-<cursor>' keys used @@ -3458,14 +3918,10 @@ Org-mode can cooperate with the following packages: Also this package uses the `S-<cursor>' keys, so everything written in the paragraph above about CUA mode also applies here. -`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. - File: org, Node: Bugs, Next: Acknowledgments, Prev: Interaction, Up: Miscellaneous -10.9 Bugs +11.9 Bugs ========= Here is a list of things that should work differently, but which I have @@ -3486,7 +3942,7 @@ found too hard to fix. autowrap. * When the application called by `C-c C-o' to open a file link fails - (for example because the application does not exits or refuses to + (for example because the application does not exist or refuses to open the file), it does so silently. No error message is displayed. @@ -3503,16 +3959,15 @@ 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. - * You can only make a single word boldface or italic. To emphasize - several words in a row, each must have the emphasize markers, like - in `*three* *bold* *words*'. + * Several words in a rom may *be made bold*, but this does not work + if the string is distributed over two lines. * The exporters work well, but could be made more efficient. File: org, Node: Acknowledgments, Prev: Bugs, Up: Miscellaneous -10.10 Acknowledgments +11.10 Acknowledgments ===================== Org-mode was written by Carsten Dominik, who still maintains it at the @@ -3611,7 +4066,7 @@ Org-mode would not be what it is without your input. File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top -11 Index +12 Index ******** @@ -3629,7 +4084,8 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * agenda files, removing buffers: Agenda commands. (line 195) * agenda views: Agenda views. (line 6) * agenda, for single file: Timeline. (line 6) -* allout.el, conflict with: FAQ. (line 6) +* allout.el: Conflicts. (line 6) +* allout.el, conflict with: FAQ. (line 8) * angular brackets, around links: External links. (line 35) * applescript, for calendar update: iCalendar export. (line 38) * archive locations: Archiving. (line 13) @@ -3643,7 +4099,7 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * bug reports: Feedback. (line 6) * bugs: Bugs. (line 6) * calc package: Table calculations. (line 6) -* calc.el: Interaction. (line 18) +* calc.el: Cooperation. (line 6) * calculations, in tables <1>: Table calculations. (line 6) * calculations, in tables: Built-in table editor. (line 135) @@ -3654,6 +4110,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) +* checkboxes: Plain lists. (line 36) * children, subtree visibility state: Visibility cycling. (line 10) * clean outline view: Clean view. (line 6) * column formula: Column formulas. (line 6) @@ -3662,7 +4119,7 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * completion, of CamelCase links <1>: Completion. (line 6) * completion, of CamelCase links: CamelCase links. (line 6) * completion, of dictionary words: Completion. (line 6) -* completion, of file names: Handling links. (line 40) +* completion, of file names: Handling links. (line 44) * completion, of links: Handling links. (line 28) * completion, of option keywords <1>: Completion. (line 6) * completion, of option keywords: Export options. (line 6) @@ -3674,18 +4131,18 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * completion, of TODO keywords <1>: Completion. (line 6) * completion, of TODO keywords: Workflow states. (line 12) * constants, in calculations: Formula syntax. (line 26) -* constants.el: Interaction. (line 28) -* contents, global visibility state: Visibility cycling. (line 19) +* constants.el: Cooperation. (line 14) +* contents, global visibility state: Visibility cycling. (line 22) * copying, of subtrees: Structure editing. (line 6) * creating timestamps: Creating timestamps. (line 6) -* CUA.el: Interaction. (line 40) +* CUA.el: Conflicts. (line 15) * custom agenda commands: Agenda dispatcher. (line 6) * custom search strings: Custom searches. (line 6) * customization: Customization. (line 6) * 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 48) +* dangerous commands: FAQ. (line 70) * date stamps: Time stamps. (line 6) * date, reading in minibuffer: Creating timestamps. (line 68) * DEADLINE keyword: Time stamps. (line 43) @@ -3705,7 +4162,7 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * enhancing text: Enhancing text. (line 6) * evaluate time range: Creating timestamps. (line 63) * exporting: Exporting. (line 6) -* exporting a subtree: FAQ. (line 89) +* exporting a subtree: FAQ. (line 111) * exporting, not: Comment lines. (line 6) * extended TODO keywords: TODO extensions. (line 6) * external links: External links. (line 6) @@ -3713,14 +4170,14 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * feedback: Feedback. (line 6) * file links: External links. (line 6) * file links, searching: Search options. (line 6) -* file name completion: Handling links. (line 40) +* file name completion: Handling links. (line 44) * files, adding to agenda list: Agenda files. (line 12) * filing subtrees: Archiving. (line 6) * fixed width: Enhancing text. (line 30) * fixed-width sections: Export options. (line 25) * folded, subtree visibility state: Visibility cycling. (line 10) * folding, sparse trees: Sparse trees. (line 6) -* following links: Handling links. (line 55) +* following links: Handling links. (line 59) * format specifier: Formula syntax. (line 34) * format, of links: Link format. (line 6) * formula editing: Editing/debugging formulas. @@ -3731,10 +4188,11 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * formula, for table column: Column formulas. (line 6) * formula, in tables: Built-in table editor. (line 135) +* global cycling: Visibility cycling. (line 22) * global keybindings: Installation and activation. (line 6) * global TODO list: Global TODO list. (line 6) -* global visibility states: Visibility cycling. (line 19) +* global visibility states: Visibility cycling. (line 22) * GNUS links: External links. (line 6) * hand-formatted lists: Enhancing text. (line 11) * headline levels: Export options. (line 25) @@ -3751,8 +4209,8 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * iCalendar export: iCalendar export. (line 6) * in-buffer settings: Summary of in-buffer settings. (line 6) -* indentation, of tables: FAQ. (line 113) -* indirect buffers: FAQ. (line 65) +* indentation, of tables: FAQ. (line 135) +* indirect buffers: FAQ. (line 87) * inheritance, of tags: Tag inheritance. (line 6) * inserting links: Handling links. (line 28) * installation: Installation and activation. @@ -3770,15 +4228,15 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * link format: Link format. (line 6) * links, external: External links. (line 6) * links, internal: Internal links. (line 6) -* links, returning to: Handling links. (line 81) +* links, returning to: Handling links. (line 85) * Lisp forms, as table fomulas: 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 65) -* mark ring: Handling links. (line 77) +* make-indirect-buffer: FAQ. (line 87) +* mark ring: Handling links. (line 81) * marking characters, tables: Advanced features. (line 34) * matching, of tags: Matching headline tags. (line 6) @@ -3798,14 +4256,16 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * options, for export: Export options. (line 6) * ordered lists: Plain lists. (line 6) * org-agenda, command: Weekly/Daily agenda. (line 9) +* org-checklet.el: Extensions. (line 8) * org-mode, turning on: Installation and activation. - (line 28) -* org-mouse.el: Interaction. (line 8) + (line 30) +* org-mouse.el: Extensions. (line 13) +* org-publish.el: Extensions. (line 21) * orgtbl-mode: orgtbl-mode. (line 6) * outline tree: Headlines. (line 6) * outline-mode: Outlines. (line 6) * outlines: Outlines. (line 6) -* overview, global visibility state: Visibility cycling. (line 19) +* overview, global visibility state: Visibility cycling. (line 22) * packages, interaction with other: Interaction. (line 6) * pasting, of subtrees: Structure editing. (line 6) * per file keywords: Per file keywords. (line 6) @@ -3825,7 +4285,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>: Interaction. (line 64) +* remember.el <1>: Cooperation. (line 29) * remember.el: Remember. (line 6) * richer text: Enhancing text. (line 6) * RMAIL links: External links. (line 6) @@ -3835,9 +4295,9 @@ 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 48) -* show all, command: Visibility cycling. (line 27) -* show all, global visibility state: Visibility cycling. (line 19) +* 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) * single file summary: Timeline. (line 6) * sorting, of agenda items: Sorting of agenda items. @@ -3852,6 +4312,7 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * storing links: Handling links. (line 9) * structure editing: Structure editing. (line 6) * structure of document: Document structure. (line 6) +* subtree cycling: Visibility cycling. (line 10) * subtree visibility states: Visibility cycling. (line 10) * subtree, cut and paste: Structure editing. (line 6) * subtree, subtree visibility state: Visibility cycling. (line 10) @@ -3862,7 +4323,7 @@ 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>: Interaction. (line 14) +* table.el <1>: Cooperation. (line 30) * table.el: table.el. (line 6) * tables <1>: Export options. (line 25) * tables: Tables. (line 6) @@ -3872,7 +4333,7 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * tags: Tags. (line 6) * tags view: Matching headline tags. (line 6) -* templates, for remember: Remember. (line 26) +* templates, for remember: Remember. (line 23) * TeX interpretation: Enhancing text. (line 17) * TeX macros: Export options. (line 25) * TeX symbol completion: Completion. (line 6) @@ -3908,14 +4369,14 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * visible text, printing: Sparse trees. (line 39) * VM links: External links. (line 6) * WANDERLUST links: External links. (line 6) -* windmove.el: Interaction. (line 60) +* windmove.el: Conflicts. (line 33) * workflow states as TODO keywords: Workflow states. (line 6) -* XML export: XML export. (line 6) +* XOXO export: XOXO export. (line 6) File: org, Node: Key Index, Prev: Index, Up: Top -12 Key Index +13 Key Index ************ @@ -3937,7 +4398,7 @@ File: org, Node: Key Index, Prev: Index, Up: Top * <TAB> <1>: Agenda commands. (line 35) * <TAB> <2>: Built-in table editor. (line 57) -* <TAB> <3>: Plain lists. (line 38) +* <TAB> <3>: Plain lists. (line 48) * <TAB>: Visibility cycling. (line 10) * > <1>: Agenda commands. (line 148) * >: Creating timestamps. (line 76) @@ -3948,8 +4409,8 @@ File: org, Node: Key Index, Prev: Index, Up: Top * C-,: Agenda files. (line 18) * C-c !: Creating timestamps. (line 21) * C-c $: Archiving. (line 9) -* C-c %: Handling links. (line 77) -* C-c &: Handling links. (line 81) +* C-c %: Handling links. (line 81) +* C-c &: Handling links. (line 85) * C-c ' <1>: Editing/debugging formulas. (line 20) * C-c ': Built-in table editor. @@ -3993,7 +4454,7 @@ File: org, Node: Key Index, Prev: Index, Up: Top * C-c a T: Global TODO list. (line 15) * C-c a t <1>: Global TODO list. (line 9) * C-c a t: TODO basics. (line 27) -* C-c C-a: Visibility cycling. (line 27) +* C-c C-a: Visibility cycling. (line 31) * C-c C-b: Motion. (line 15) * C-c C-c <1>: The very busy C-c C-c key. (line 6) @@ -4003,7 +4464,7 @@ File: org, Node: Key Index, Prev: Index, Up: Top (line 16) * C-c C-c <5>: Built-in table editor. (line 54) -* C-c C-c: Plain lists. (line 68) +* C-c C-c: Plain lists. (line 79) * C-c C-d <1>: Agenda commands. (line 133) * C-c C-d: Creating timestamps. (line 37) * C-c C-f: Motion. (line 12) @@ -4011,7 +4472,7 @@ File: org, Node: Key Index, Prev: Index, Up: Top * C-c C-l: Handling links. (line 28) * C-c C-n: Motion. (line 8) * C-c C-o <1>: Creating timestamps. (line 33) -* C-c C-o: Handling links. (line 55) +* C-c C-o: Handling links. (line 59) * C-c C-p: Motion. (line 9) * C-c C-q <1>: Editing/debugging formulas. (line 20) @@ -4033,7 +4494,7 @@ File: org, Node: Key Index, Prev: Index, Up: Top * C-c C-x C-w <1>: Built-in table editor. (line 108) * C-c C-x C-w: Structure editing. (line 36) -* C-c C-x C-x: XML export. (line 10) +* C-c C-x C-x: XOXO export. (line 10) * C-c C-x C-y <1>: Built-in table editor. (line 112) * C-c C-x C-y: Structure editing. (line 43) @@ -4043,7 +4504,7 @@ File: org, Node: Key Index, Prev: Index, Up: Top (line 105) * C-c C-x M-w: Structure editing. (line 40) * C-c C-x t: Export options. (line 13) -* C-c C-x v <1>: XML export. (line 11) +* C-c C-x v <1>: XOXO export. (line 11) * C-c C-x v: Sparse trees. (line 39) * C-c C-x v a: ASCII export. (line 13) * C-c C-x v b: HTML export. (line 14) @@ -4056,7 +4517,7 @@ File: org, Node: Key Index, Prev: Index, Up: Top * 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 40) +* C-u C-c C-l: Handling links. (line 44) * D: Agenda commands. (line 68) * d: Agenda commands. (line 65) * f: Agenda commands. (line 44) @@ -4071,7 +4532,7 @@ File: org, Node: Key Index, Prev: Index, Up: Top * M-<left> <1>: Built-in table editor. (line 72) * M-<left>: Structure editing. (line 18) -* M-<RET> <1>: Plain lists. (line 43) +* M-<RET> <1>: Plain lists. (line 53) * M-<RET>: Structure editing. (line 6) * M-<right> <1>: Built-in table editor. (line 72) @@ -4083,30 +4544,30 @@ File: org, Node: Key Index, Prev: Index, Up: Top (line 82) * M-S-<down> <1>: Built-in table editor. (line 89) -* M-S-<down> <2>: Plain lists. (line 53) +* M-S-<down> <2>: Plain lists. (line 64) * M-S-<down>: Structure editing. (line 33) * M-S-<left> <1>: Creating timestamps. (line 97) * M-S-<left> <2>: Built-in table editor. (line 76) -* M-S-<left> <3>: Plain lists. (line 59) +* M-S-<left> <3>: Plain lists. (line 70) * M-S-<left>: Structure editing. (line 24) * M-S-<RET>: Structure editing. (line 15) * M-S-<right> <1>: Creating timestamps. (line 94) * M-S-<right> <2>: Built-in table editor. (line 79) -* M-S-<right> <3>: Plain lists. (line 59) +* M-S-<right> <3>: Plain lists. (line 70) * M-S-<right>: Structure editing. (line 27) * M-S-<up> <1>: Built-in table editor. (line 86) -* M-S-<up> <2>: Plain lists. (line 53) +* M-S-<up> <2>: Plain lists. (line 64) * M-S-<up>: Structure editing. (line 30) * mouse-1 <1>: Agenda commands. (line 35) * mouse-1 <2>: Creating timestamps. (line 79) -* mouse-1: Handling links. (line 69) +* mouse-1: Handling links. (line 73) * mouse-2 <1>: Agenda commands. (line 35) -* mouse-2: Handling links. (line 69) +* mouse-2: Handling links. (line 73) * mouse-3 <1>: Agenda commands. (line 28) -* mouse-3: Handling links. (line 74) +* mouse-3: Handling links. (line 78) * n: Agenda commands. (line 19) * o: Agenda commands. (line 59) * P: Agenda commands. (line 117) @@ -4126,7 +4587,7 @@ File: org, Node: Key Index, Prev: Index, Up: Top * S-<right>: Creating timestamps. (line 50) * S-<TAB> <1>: Built-in table editor. (line 61) -* S-<TAB>: Visibility cycling. (line 19) +* S-<TAB>: Visibility cycling. (line 22) * S-<up> <1>: Agenda commands. (line 120) * S-<up> <2>: Creating timestamps. (line 55) * S-<up>: Priorities. (line 25) @@ -4139,101 +4600,119 @@ File: org, Node: Key Index, Prev: Index, Up: Top Tag Table: Node: Top959 -Node: Introduction7583 -Node: Summary7897 -Node: Installation and activation10005 -Node: Feedback11674 -Node: Document structure12460 -Node: Outlines13226 -Node: Headlines13886 -Node: Visibility cycling14509 -Node: Motion15705 -Node: Structure editing16489 -Node: Archiving18598 -Node: Sparse trees19458 -Ref: Sparse trees-Footnote-121443 -Ref: Sparse trees-Footnote-221535 -Node: Plain lists21650 -Ref: Plain lists-Footnote-124944 -Node: Tables25301 -Node: Built-in table editor25849 -Node: Narrow columns33462 -Ref: Narrow columns-Footnote-135401 -Node: Table calculations35447 -Node: Formula syntax36767 -Ref: Formula syntax-Footnote-139672 -Node: Lisp formulas39971 -Node: Column formulas40762 -Node: Advanced features42523 -Node: Named-field formulas45778 -Node: Editing/debugging formulas46418 -Node: Appetizer48176 -Node: orgtbl-mode49278 -Node: table.el49769 -Node: Hyperlinks50746 -Node: Link format51450 -Node: Internal links52747 -Node: Radio targets54697 -Node: CamelCase links55412 -Node: External links55910 -Node: Handling links57835 -Node: Search options62167 -Ref: Search options-Footnote-163943 -Node: Custom searches64024 -Node: Remember65072 -Ref: Remember-Footnote-168939 -Node: TODO items69063 -Node: TODO basics69986 -Node: Progress logging71327 -Node: TODO extensions72113 -Node: Workflow states72913 -Node: TODO types73781 -Ref: TODO types-Footnote-175439 -Node: Per file keywords75521 -Ref: Per file keywords-Footnote-176974 -Node: Priorities77202 -Node: Timestamps78411 -Node: Time stamps78732 -Node: Creating timestamps81160 -Node: Tags84289 -Node: Tag inheritance85024 -Node: Setting tags85961 -Node: Tag searches86923 -Node: Agenda views88132 -Node: Agenda files89671 -Ref: Agenda files-Footnote-190631 -Ref: Agenda files-Footnote-290780 -Node: Agenda dispatcher90972 -Node: Weekly/Daily agenda93102 -Node: Categories94237 -Node: Time-of-day specifications94885 -Node: Calendar/Diary integration96861 -Node: Sorting of agenda items98238 -Node: Global TODO list99070 -Node: Matching headline tags100485 -Node: Timeline101428 -Node: Agenda commands102301 -Node: Exporting107771 -Node: ASCII export108901 -Node: HTML export109791 -Node: XML export111622 -Node: iCalendar export112057 -Node: Text interpretation113879 -Node: Comment lines114356 -Node: Enhancing text114825 -Node: Export options116656 -Node: Miscellaneous118258 -Node: Completion119016 -Node: Customization120012 -Node: Summary of in-buffer settings120619 -Node: The very busy C-c C-c key123380 -Node: Clean view124785 -Node: TTY keys127362 -Node: FAQ128963 -Node: Interaction135865 -Node: Bugs138899 -Node: Acknowledgments140853 -Node: Index144222 -Node: Key Index165665 +Node: Introduction8559 +Node: Summary8873 +Node: Installation and activation11129 +Node: Feedback12787 +Node: Document structure13573 +Node: Outlines14339 +Node: Headlines14999 +Node: Visibility cycling15622 +Ref: Visibility cycling-Footnote-117097 +Ref: Visibility cycling-Footnote-217155 +Node: Motion17205 +Node: Structure editing17989 +Node: Archiving20098 +Node: Sparse trees20958 +Ref: Sparse trees-Footnote-122943 +Ref: Sparse trees-Footnote-223035 +Node: Plain lists23150 +Ref: Plain lists-Footnote-126868 +Node: Tables27225 +Node: Built-in table editor27773 +Node: Narrow columns35386 +Ref: Narrow columns-Footnote-137325 +Node: Table calculations37371 +Node: Formula syntax38691 +Ref: Formula syntax-Footnote-141596 +Node: Lisp formulas41895 +Node: Column formulas42686 +Node: Advanced features44447 +Node: Named-field formulas47702 +Node: Editing/debugging formulas48342 +Node: Appetizer50100 +Node: orgtbl-mode51202 +Node: table.el51693 +Node: Hyperlinks52670 +Node: Link format53374 +Node: Internal links54671 +Node: Radio targets56621 +Node: CamelCase links57336 +Node: External links57834 +Node: Handling links59759 +Node: Search options64312 +Ref: Search options-Footnote-166088 +Node: Custom searches66169 +Node: Remember67217 +Node: TODO items70903 +Node: TODO basics71826 +Node: Progress logging73167 +Node: TODO extensions73953 +Node: Workflow states74753 +Node: TODO types75621 +Ref: TODO types-Footnote-177279 +Node: Per file keywords77361 +Ref: Per file keywords-Footnote-178814 +Node: Priorities79042 +Node: Timestamps80249 +Node: Time stamps80570 +Node: Creating timestamps82998 +Node: Tags86123 +Node: Tag inheritance86858 +Node: Setting tags87795 +Node: Tag searches88757 +Node: Agenda views89966 +Node: Agenda files91505 +Ref: Agenda files-Footnote-192465 +Ref: Agenda files-Footnote-292614 +Node: Agenda dispatcher92806 +Node: Weekly/Daily agenda94936 +Node: Categories96071 +Node: Time-of-day specifications96719 +Node: Calendar/Diary integration98695 +Node: Sorting of agenda items100072 +Node: Global TODO list100904 +Node: Matching headline tags102319 +Node: Timeline103262 +Node: Agenda commands104135 +Node: Exporting109605 +Node: ASCII export110734 +Node: HTML export111624 +Node: XOXO export113850 +Node: iCalendar export114289 +Node: Text interpretation116112 +Node: Comment lines116589 +Node: Enhancing text117058 +Node: Export options118889 +Node: Publishing120491 +Ref: Publishing-Footnote-1121287 +Node: Configuration121483 +Node: Project alist122144 +Node: File sources and destinations123202 +Node: Selecting files123754 +Node: Publishing action124507 +Node: Publishing options125621 +Node: Links127648 +Node: Project page index128440 +Node: Sample configuration129207 +Node: Simple example129699 +Node: Complex example130372 +Node: Triggering publication132406 +Node: Miscellaneous133062 +Node: Completion133821 +Node: Customization134817 +Node: Summary of in-buffer settings135424 +Node: The very busy C-c C-c key138429 +Node: Clean view139941 +Node: TTY keys142518 +Node: FAQ144119 +Node: Interaction151860 +Node: Extensions152320 +Node: Cooperation153889 +Node: Conflicts155583 +Node: Bugs157175 +Node: Acknowledgments159073 +Node: Index162442 +Node: Key Index184323 End Tag Table diff --git a/org-install.el b/org-install.el new file mode 100644 index 0000000..435027f --- /dev/null +++ b/org-install.el @@ -0,0 +1,27 @@ +;;; org-install.el --- Autoloads for org.el + +(autoload 'org-mode "org" "Org mode" t) +(autoload 'org-diary "org" "Diary entries from Org mode.") +(autoload 'org-agenda "org" "Multi-file agenda from Org mode." t) +(autoload 'org-store-link "org" "Store a link to the current location." t) +(autoload 'orgtbl-mode "org" "Org tables as a minor mode." t) +(autoload 'turn-on-orgtbl "org" "Org tables as a minor mode.") +(autoload 'org-cycle "org" "Subtree visibility cycling." t) +(autoload 'org-global-cycle "org" "Global visibility cycling." t) +(autoload 'org-agenda-list "org" "Produce calendar-loke agenda view." t) +(autoload 'org-todo-list "org" "Produce global TODO list." t) +(autoload 'org-tags-view "org" "Produce global TAGS agenda view." t) +(autoload 'org-remember-annotation "org") +(autoload 'org-remember-apply-template "org") +(autoload 'org-remember-handler "org") +(autoload 'org-export-icalendar-all-agenda-files "org" + "Export all files in `org-agenda-files' to iCalendar .ics files." t) +(autoload 'org-export-icalendar-combine-agenda-files "org" + "Export all files in `org-agenda-files' to a single combined iCalendar file." t) +(autoload 'org-publish-current-file "org-publish" "Publish current file." t) +(autoload 'org-publish-current-project "org-publish" + "Publish all files of current project." t) +(autoload 'org-publish "org-publish" "Publish a project." t) +(autoload 'org-publish-all "org-publish" "Publish all projects." t) + +(provide 'org-install) diff --git a/org-publish.el b/org-publish.el new file mode 100644 index 0000000..2a1ba58 --- /dev/null +++ b/org-publish.el @@ -0,0 +1,561 @@ +;;; org-publish.el --- publish related org-mode files as a website + +;; Copyright (C) 2006 David O'Toole + +;; Author: David O'Toole <dto@gnu.org> +;; Keywords: hypermedia, outlines +;; Version: + +;; $Id: org-publish.el,v 1.61 2006/05/19 12:03:51 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 +;; the Free Software Foundation; either version 2, or (at your option) +;; any later version. + +;; This file 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. + +;; This file is NOT part of GNU Emacs. + +;;; Commentary: + +;; Requires at least version 4.27 of org.el +;; +;; The official org-mode website: +;; http://staff.science.uva.nl/~dominik/Tools/org/ +;; +;; Home page for org-publish.el: +;; http://dto.freeshell.org/notebook/OrgMode.html + +;; This program extends the HTML publishing support of Emacs Org-mode +;; to allow configurable publishing of related sets of files as a +;; complete website. +;; +;; 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 +;; + Exclude selected private pages from publishing +;; + Publish a clickable index of pages +;; + Manage local timestamps, for publishing only changed files +;; + Accept plugin functions to extend range of publishable content +;; +;; Special thanks to the org-mode maintainer Carsten Dominik for his +;; ideas, enthusiasm, and cooperation. + +;;; Installation: + +;; Put org-publish.el in your load path, byte-compile it, and then add +;; the following lines to your emacs initialization file: + +;; (autoload 'org-publish "org-publish" nil t) +;; (autoload 'org-publish "org-publish-all" nil t) +;; (autoload 'org-publish "org-publish-current-file" nil t) +;; (autoload 'org-publish "org-publish-current-project" nil t) + +;;; Usage: +;; +;; The program's main configuration variable is +;; `org-publish-project-alist'. See below for example configurations +;; with commentary. + +;; The main interactive functions are: +;; +;; M-x org-publish +;; M-x org-publish-all +;; M-x org-publish-current-file +;; M-x org-publish-current-project + +;;;; Simple example configuration: + +;; (setq org-publish-project-alist +;; (list +;; '("org" . (:base-directory "~/org/" +;; :base-extension "org" +;; :publishing-directory "~/public_html" +;; :with-section-numbers nil +;; :table-of-contents nil +;; :style "<link rel=stylesheet href=\"../other/mystyle.css\" type=\"text/css\">"))) + +;;;; More complex example configuration: + +;; Imagine your *.org files are kept in ~/org, your images in +;; ~/images, and stylesheets in ~/other. Now imagine you want to +;; publish the files through an ssh connection to a remote host, via +;; Tramp-mode. To maintain relative links from *.org files to /images +;; and /other, we should replicate the same directory structure in +;; your web server account's designated html root (in this case, +;; assumed to be ~/html) + +;; Once you've done created the proper directories, you can adapt the +;; 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. + +;; (setq org-publish-project-alist +;; (list +;; '("website" . +;; (("orgfiles" :base-directory "~/org/" +;; :base-extension "org" +;; :publishing-directory "/ssh:user@host:~/html/notebook/" +;; :publishing-function org-publish-org-to-html +;; :exclude "PrivatePage.org" ;; regexp +;; :headline-levels 3 +;; :with-section-numbers nil +;; :table-of-contents nil +;; :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/" +;; :publishing-function org-publish-attachment))))) + +;; For more information, see the documentation for the variable +;; `org-publish-project-alist'. + +;; Of course, you don't have to publish to remote directories from +;; within emacs. You can always just publish to local folders, and +;; then use the synchronization/upload tool of your choice. + + +;;; List of user-visible changes since version 1.27 + +;; 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.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. +;; 1.37: Added interactive function "org-publish". Prompts for particular +;; project name to publish. +;; 1.34: Added force-publish option to all interactive functions. +;; 1.32: Fixed "index.org has changed on disk" error during index publishing. +;; 1.30: Fixed startup error caused by (require 'em-unix) + +;;; Code: + +;; these lines get code for function "eshell/cp" loaded +(require 'eshell) +(require 'esh-maint) +(require 'em-unix) +(require 'org) + +(defgroup org-publish nil + "Options for publishing a set of Org-mode and related files." + :tag "Org Publishing" + :group 'org) + + +(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 either a property list with configuration +options for the publishing process (see below), or a list of the +following form: + + ((\"component1\" :property value :property value ... ) + (\"component2\" :property value :property value ... )) + +When the CDR of an element of org-publish-project-alist is in +this second form, the elements of this list are taken to be +components of the project, which group together files requiring +different publishing options. + +When a property is given a value in org-publish-project-alist, its +setting overrides the value of the corresponding user variable + (if any) during publishing. However, options set within a file +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. + :publishing-directory Directory (possibly remote) where output + files will be published + +The :exclude property may be used to prevent certain files from +being published. Its value may be a string or regexp matching +file names you don't want to be published. + +The :include property may be used to include extra files. Its +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. + +One special property controls which back-end function to use for +publishing files in the project. This can be used to extend the +set of file types publishable by org-publish, as well as the set +of output formats. + + :publishing-function Function to publish file. The default is + org-publish-org-to-html, but other + values are possible. + +Some properties control details of the Org publishing process, +and are equivalent to the corresponding user variables listed in +the right column. See the documentation for those variables to +learn more about their use and default values. + + :language org-export-default-language + :headline-levels org-export-headline-levels + :section-numbers org-export-with-section-numbers + :table-of-contents org-export-with-toc + :emphasize org-export-with-emphasize + :sub-superscript org-export-with-sub-superscripts + :TeX-macros org-export-with-TeX-macros + :fixed-width org-export-with-fixed-width + :tables org-export-with-tables + :table-auto-headline org-export-highlight-first-table-line + :style org-export-html-style + :convert-org-links org-export-html-link-org-files-as-html + :inline-images org-export-html-inline-images + :expand-quoted-html org-export-html-expand + :timestamp org-export-html-with-timestamp + :publishing-directory org-export-publishing-directory + :preamble org-export-html-preamble + :postamble org-export-html-postamble + :auto-preamble org-export-html-auto-preamble + :auto-postamble org-export-html-auto-postamble + :author user-full-name + :email user-mail-address + +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 + 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 + generates a plain list of links to all files + 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 nil, do no timestamp checking and always publish all +files." + :group 'org-publish + :type 'boolean) + + +(defcustom org-publish-timestamp-directory "~/.org-timestamps/" + "Name of directory in which to store publishing timestamps." + :group 'org-publish + :type 'string) + + +;;;; Timestamp-related functions + + +(defun org-publish-timestamp-filename (filename) + "Return path to timestamp file for filename FILENAME." + (while (string-match "~\\|/" filename) + (setq filename (replace-match "_" nil t filename))) + (concat org-publish-timestamp-directory filename ".timestamp")) + + +(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." + (if org-publish-use-timestamps-flag + (progn + ;; + ;; create folder if needed + (if (not (file-exists-p org-publish-timestamp-directory)) + (make-directory org-publish-timestamp-directory) + (if (not (file-directory-p org-publish-timestamp-directory)) + (error "org-publish-timestamp-directory must be a directory."))) + ;; + ;; 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 + ;; handle new timestamps + (if (not (file-exists-p timestamp)) + ;; create file + (with-temp-buffer + (write-file timestamp) + (kill-buffer (current-buffer))))) + rtn)) + t)) + + +(defun org-publish-update-timestamp (filename) + "Update publishing timestamp for file FILENAME." + (let ((timestamp (org-publish-timestamp-filename filename))) + (set-file-times timestamp))) + + +;;;; Utilities + + +(defun org-publish-get-project (project-name) + "Return project object for project PROJECT-NAME." + (let ((project (assoc project-name org-publish-project-alist))) + (if project + (cdr project) + nil))) + + +(defun org-publish-get-project-component (project-name component-name) + "Return plist for project component COMPONENT-NAME within project PROJECT-NAME." + (let* ((components (org-publish-get-project project-name)) + (c nil) + (plist nil)) + (while (setq c (pop components)) + (when (and (stringp (car c)) (string= component-name (car c))) + (setq plist (cdr c)))) + plist)) + + +(defun org-publish-composite-project-p (element) + "Tell whether an ELEMENT of org-publish-project-alist is composite." + (listp (car (cdr element)))) + + +(defun org-publish-iterate-project-plists (action &optional project-name) + "Call function ACTION for each project component. +ACTION should accept two arguments: the name of the enclosing +project, and the property list associated with the project +component. If PROJECT-NAME is set, iterate only over components +of that project." + (let ((alist (if project-name + `((,project-name ,@(org-publish-get-project project-name))) + org-publish-project-alist)) + (project nil)) + (while (setq project (pop alist)) + (if (org-publish-composite-project-p project) + ;; + ;; handle composite project + (let ((components (cdr project)) + (c nil)) + (while (setq c (pop components)) + (let ((plist (cdr c))) + (funcall action (car project) plist)))) + ;; + ;; handle normal project + (let ((plist (cdr project))) + (funcall action (car project) plist)))))) + + + +(defun org-publish-get-base-files (plist &optional exclude-regexp) + "Return a list of all files in project defined by PLIST. +If EXCLUDE-REGEXP is set, this will be used to filter out +matching filenames." + (let* ((dir (file-name-as-directory (plist-get plist :base-directory))) + (include-list (plist-get plist :include)) + (extension (or (plist-get plist :base-extension) "org")) + (regexp (concat "^[^\\.].*\\.\\(" extension "\\)$")) + (allfiles (directory-files dir t regexp))) + ;; + ;; exclude files + (setq allfiles + (if (not exclude-regexp) + allfiles + (delq nil + (mapcar (lambda (x) + (if (string-match exclude-regexp x) nil x)) + allfiles)))) + ;; + ;; include extra files + (let ((inc nil)) + (while (setq inc (pop include-list)) + (setq allfiles (cons (concat dir inc) allfiles)))) + + allfiles)) + + +(defun org-publish-get-project-from-filename (filename) + "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)) + (org-publish-iterate-project-plists + (lambda (project-name project-plist) + (let ((files (org-publish-get-base-files project-plist))) + (if (member (expand-file-name filename) files) + (setq found project-name))))) + found)) + + +(defun org-publish-get-plist-from-filename (filename) + "Return publishing configuration plist for file FILENAME." + (let ((found nil)) + (org-publish-iterate-project-plists + (lambda (project-name project-plist) + (let ((files (org-publish-get-base-files project-plist))) + (if (member (expand-file-name filename) files) + (setq found project-plist))))) + 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. +FILENAME is the filename of the org file to be published." + (let* ((arg (plist-get plist :headline-levels))) + (progn + (find-file filename) + (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. +FILENAME is the filename of the file to be published." + (let ((destination (file-name-as-directory (plist-get plist :publishing-directory)))) + (eshell/cp filename destination))) + + +;;;; Publishing files, projects, and indices + + +(defun org-publish-file (filename) + "Publish file FILENAME." + (let* ((project-name (org-publish-get-project-from-filename filename)) + (plist (org-publish-get-plist-from-filename filename)) + (publishing-function (or (plist-get plist :publishing-function) 'org-publish-org-to-html))) + (if (not project-name) + (error (format "File %s is not part of any known project." filename))) + (when (org-publish-needed-p filename) + (funcall publishing-function plist filename) + (org-publish-update-timestamp filename)))) + + +(defun org-publish-project-plist (plist) + "Publish all base files in project defined by PLIST. + 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)) + (f nil)) + ;; + (if index-p + (funcall index-function plist index-filename)) + (let ((files (org-publish-get-base-files plist exclude-regexp))) + (while (setq f (pop files)) + ;; 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))) + + +(defun org-publish-org-index (plist &optional index-filename) + "Create an index of pages in project 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)) + (files (org-publish-get-base-files plist exclude-regexp)) + (index-filename (concat dir (or index-filename "index.org"))) + (index-buffer (find-buffer-visiting index-filename)) + (ifn (file-name-nondirectory index-filename)) + (f nil)) + ;; + ;; if buffer is already open, kill it to prevent error message + (if index-buffer + (kill-buffer index-buffer)) + (with-temp-buffer + (while (setq f (pop files)) + (let ((fn (file-name-nondirectory f))) + (unless (string= fn ifn) ;; index shouldn't index itself + (insert (concat " + [[file:" fn "][" + (file-name-sans-extension fn) + "]]\n"))))) + (write-file index-filename) + (kill-buffer (current-buffer))))) + + +;;;; Interactive publishing functions + + +;;;###autoload +(defun org-publish (project-name &optional force) + "Publish the project PROJECT-NAME." + (interactive "sProject name: \nP") + (let ((org-publish-use-timestamps-flag (if force nil t))) + (org-publish-iterate-project-plists + (lambda (ignore project-plist) + (org-publish-project-plist project-plist)) + project-name))) + + +;;;###autoload +(defun org-publish-current-project (&optional force) + "Publish the project associated with the current file. +With prefix argument, force publishing all files in project." + (interactive "P") + (let* ((project-name (org-publish-get-project-from-filename (buffer-file-name))) + (org-publish-use-timestamps-flag (if force nil t))) + (if (not project-name) + (error (format "File %s is not part of any known project." (buffer-file-name)))) + (org-publish project-name))) + + +;;;###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 + (if force nil t))) + (org-publish-file (buffer-file-name)))) + + +;;;###autoload +(defun org-publish-all (&optional force) + "Publish all projects. +With prefix argument, force publish all files." + (interactive "P") + (let ((org-publish-use-timestamps-flag + (if force nil t))) + (org-publish-iterate-project-plists + (lambda (project-name project-plist) + (org-publish-project-plist project-plist))))) + + + + +(provide 'org-publish) +;;; org-publish.el ends here @@ -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.29 +;; Version: 4.30 ;; ;; This file is part of GNU Emacs. ;; @@ -52,16 +52,17 @@ ;; (define-key global-map "\C-cl" 'org-store-link) ;; (define-key global-map "\C-ca" 'org-agenda) ;; -;; If you have downloaded Org-mode from the Web, you must byte-compile -;; org.el and put it on your load path. In addition to the Emacs Lisp -;; lines above, you also need to add the following lines to .emacs: +;; Furthermore you need to activate font-lock-mode in org-mode buffers. +;; either of the following two lins will do the trick: ;; -;; (autoload 'org-mode "org" "Org mode" t) -;; (autoload 'org-diary "org" "Diary entries from Org mode") -;; (autoload 'org-agenda "org" "Multi-file agenda from Org mode" t) -;; (autoload 'org-store-link "org" "Store a link to the current location" t) -;; (autoload 'orgtbl-mode "org" "Org tables as a minor mode" t) -;; (autoload 'turn-on-orgtbl "org" "Org tables as a minor mode") +;; (global-font-lock-mode 1) ; for all buffers +;; (add-hook 'org-mode-hook 'turn-on-font-lock) ; org-mode buffers only +;; +;; If you have downloaded Org-mode from the Web, you have to take additional +;; action: Byte-compile org.el and org-publish.el and put them together with +;; org-install.el on your load path. Then also add to your .emacs file: +;; +;; (require 'org-install) ;; ;; This setup will put all files with extension ".org" into Org-mode. As ;; an alternative, make the first line of a file look like this: @@ -81,6 +82,17 @@ ;; ;; Changes since version 4.10: ;; --------------------------- +;; Version 4.30 +;; - Modified installation: Autoloads have been collected in org-install.el. +;; - Logging (org-log-done) is now a #+STARTUP option. +;; - Checkboxes in plain list items, following up on Frank Ruell's idea. +;; - File links inserted with C-c C-l will use relative paths if the linked +;; file is in the current directory or a subdirectory of it. +;; - New variable `org-link-file-path-type' to specify preference for +;; relative and absolute paths. +;; - New CSS classes for tags, timestamps, timestamp keywords. +;; - Bug and typo fixes. +;; ;; Version 4.29 ;; - Inlining images in HTML export now depends on wheather the link ;; contains a description or not. @@ -348,6 +360,18 @@ An entry can be toggled between QUOTE and normal with :tag "Org Cycle" :group 'org-structure) +(defcustom org-cycle-global-at-bob t + "Cycle globally if cursor is at beginning of buffer and not at a headline. +This makes it possible to do global cycling without having to use S-TAB or +C-u TAB. For this special case to work, the first line of the buffer +must not be a headline - it may be empty ot some other text. When used in +this way, `org-cycle-hook' is disables temporarily, to make sure the +cursor stays at the beginning of the buffer. +When this option is nil, don't do anything special at the beginning +of the buffer." + :group 'org-cycle + :type 'boolean) + (defcustom org-cycle-emulate-tab t "Where should `org-cycle' emulate TAB. nil Never @@ -784,6 +808,23 @@ additional URL: prefix, so the format would be \"<URL:%s>\"." (const :tag "\"<URL:%s>\" (e.g. <URL:http://www.there.com>)" "<URL:%s>") (string :tag "Other" :value "<%s>"))) +(defcustom org-link-file-path-type 'adaptive + "How the path name in file links should be stored. +Valid values are: + +relative relative to the current directory, i.e. the directory of the file + into which the link is being inserted. +absolute absolute path, if possible with ~ for home directory. +noabbrev absolute path, no abbreviation of home directory. +adaptive Use relative path for files in the current directory and sub- + directories of it. For other files, use an absolute path." + :group 'org-link + :type '(choice + (const relative) + (const absolute) + (const noabbrev) + (const adaptive))) + (defcustom org-activate-links '(bracket angle plain radio tag date) "Types of links that should be activated in Org-mode files. This is a list of symbols, each leading to the activation of a certain link @@ -962,7 +1003,11 @@ for some files for which the OS does not have a good default. See `org-file-apps'.") (defconst org-file-apps-defaults-windowsnt - '((t . (w32-shell-execute "open" file))) + (list (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'.") @@ -979,14 +1024,20 @@ See `org-file-apps'.") "External applications for opening `file:path' items in a document. Org-mode uses system defaults for different file types, but you can use this variable to set the application for a given file -extension. The entries in this list are cons cells with a file extension -and the corresponding command. Possible values for the command are: - `emacs' The file will be visited by the current Emacs process. - `default' Use the default application for this file type. - string A command to be executed by a shell; %s will be replaced - by the path to the file. - sexp A Lisp form which will be evaluated. The file path will - be available in the Lisp variable `file'. +extension. The entries in this list are cons cells where the car identifies +files and the cdr the corresponding command. Possible values for the +file identifier are + \"ext\" A string identifying an extension + `directory' Matches a directory + t Default for all remaining files + +Possible values for the command are: + `emacs' The file will be visited by the current Emacs process. + `default' Use the default application for this file type. + string A command to be executed by a shell; %s will be replaced + by the path to the file. + sexp A Lisp form which will be evaluated. The file path will + be available in the Lisp variable `file'. For more examples, see the system specific constants `org-file-apps-defaults-macosx' `org-file-apps-defaults-windowsnt' @@ -1114,7 +1165,12 @@ Lisp variable `state'." (defcustom org-log-done nil "When set, insert a (non-active) time stamp when TODO entry is marked DONE. When the state of an entry is changed from nothing to TODO, remove a previous -closing date." +closing date. +This can also be configured on a per-file basis by adding one of +the following lines anywhere in the buffer: + + #+STARTUP: logging + #+STARTUP: nologging" :group 'org-todo :type 'boolean) @@ -1139,6 +1195,14 @@ This is the priority an item get if no explicit priority is given." :tag "Org Time" :group 'org) +(defcustom org-insert-labeled-timestamps-at-point nil + "Non-nil means, SCHEDULED and DEADLINE timestamps are inserted at point. +When nil, these labeled time stamps are forces into the second line of an +entry, just after the headline. When scheduling from the global TODO list, +the time stamp will always be forced into the second line." + :group 'org-time + :type 'boolean) + (defconst org-time-stamp-formats '("<%Y-%m-%d %a>" . "<%Y-%m-%d %a %H:%M>") "Formats for `format-time-string' which are used for time stamps. It is not recommended to change this constant.") @@ -1652,6 +1716,11 @@ This option can also be set with the +OPTIONS line, e.g. \"\\n:t\"." :group 'org-export-general :type 'boolean) +(defcustom org-export-with-timestamps t + "Nil means, do not export time stamps and associated keywords." + :group 'org-export + :type 'boolean) + (defcustom org-export-with-tags t "Nil means, do not export tags, just remove them from headlines." :group 'org-export-general @@ -1796,6 +1865,8 @@ Otherwise the buffer will just be saved to a file and stay hidden." :tag "Org Export XML" :group 'org-export) +;; FIXME: I am told XOXO is not XML, it is semantic-only HTML. + (defcustom org-export-xml-type 'xoxo ;kw, if we have only one. "The kind of XML to be produced by the XML exporter. Allowed values are: @@ -1816,8 +1887,11 @@ xoxo The XOXO exporter." font-size: 12pt; } .title { text-align: center; } - .todo, .deadline { color: red; } + .todo { color: red; } .done { color: green; } + .timestamp { color: grey } + .timestamp-kwd { color: CadetBlue } + .tag { background-color:lightblue; font-weight:normal } .target { background-color: lavender; } pre { border: 1pt solid #AEBDCC; @@ -2274,6 +2348,9 @@ This face is only used if `org-fontify-done-headline' is set." (defvar org-keyword-time-regexp nil "Matches any of the 3 keywords, together with the time stamp.") (make-variable-buffer-local 'org-keyword-time-regexp) +(defvar org-maybe-keyword-time-regexp nil + "Matches a timestamp, possibly preceeded by a keyword.") +(make-variable-buffer-local 'org-keyword-time-regexp) (defun org-set-regexps-and-options () "Precompute regular expressions for current buffer." @@ -2316,6 +2393,8 @@ This face is only used if `org-fontify-done-headline' is set." ("oddeven" org-odd-levels-only nil) ("align" org-startup-align-all-tables t) ("noalign" org-startup-align-all-tables nil) + ("logging" org-log-done t) + ("nologging" org-log-done nil) ("dlcheck" org-startup-with-deadline-check t) ("nodlcheck" org-startup-with-deadline-check nil))) l var val) @@ -2370,7 +2449,12 @@ This face is only used if `org-fontify-done-headline' is set." (concat "\\<\\(" org-scheduled-string "\\|" org-deadline-string "\\|" org-closed-string "\\)" - " *[[<]\\([^]>]+\\)[]>]")) ;; FIXME: is this correct? + " *[[<]\\([^]>]+\\)[]>]") ;; FIXME: is this correct? + org-maybe-keyword-time-regexp + (concat "\\(\\<\\(" org-scheduled-string + "\\|" org-deadline-string + "\\|" org-closed-string "\\)\\)?" + " *\\([[<][0-9]\\{4\\}-[0-9]\\{2\\}-[0-9]\\{2\\}[^]\r\n>]*?[]>]\\)")) ;; FIXME: is this correct? (org-set-font-lock-defaults))) @@ -2810,11 +2894,13 @@ between words." (let* ((em org-fontify-emphasized-text) (lk org-activate-links) (org-font-lock-extra-keywords + ;; Headlines (list '("^\\(\\**\\)\\(\\*\\)\\(.*\\)" (1 (org-get-level-face 1)) (2 (org-get-level-face 2)) (3 (org-get-level-face 3))) '("^[ \t]*\\(\\(|\\|\\+-[-+]\\).*\\S-\\)" (1 'org-table)) + ;; Links (if (memq 'angle lk) '(org-activate-angle-links (0 'org-link t))) (if (memq 'plain lk) '(org-activate-plain-links (0 'org-link t))) (if (memq 'bracket lk) '(org-activate-bracket-links (0 'org-link t))) @@ -2824,27 +2910,36 @@ between words." (if (memq 'tag lk) '(org-activate-tags (1 'org-tag prepend))) (if org-table-limit-column-width '(org-hide-wide-columns (0 nil append))) + ;; TODO lines (list (concat "^\\*+[ \t]*" org-not-done-regexp) '(1 'org-todo t)) + ;; Priorities (list (concat "\\[#[A-Z]\\]") '(0 'org-special-keyword t)) + ;; Special keywords (list (concat "\\<" org-deadline-string) '(0 'org-special-keyword t)) (list (concat "\\<" org-scheduled-string) '(0 'org-special-keyword t)) (list (concat "\\<" org-closed-string) '(0 'org-special-keyword t)) -; (if em '("\\(\\W\\|^\\)\\(\\*\\w+\\*\\)\\(\\W\\|$\\)" 2 'bold prepend)) -; (if em '("\\(\\W\\|^\\)\\(/\\w+/\\)\\(\\W\\|$\\)" 2 'italic prepend)) -; (if em '("\\(\\W\\|^\\)\\(_\\w+_\\)\\(\\W\\|$\\)" 2 'underline prepend)) + ;; Emphasis (if em (list org-bold-re 2 ''bold 'prepend)) (if em (list org-italic-re 2 ''italic 'prepend)) (if em (list org-underline-re 2 ''underline 'prepend)) + ;; Checkboxes, similar to Frank Ruell's org-checklet.el + '("^[ \t]*\\([-+*]\\|[0-9]+[.)]\\) +\\(\\[_\\]\\)" + 2 'bold prepend) + '("^[ \t]*\\([-+*]\\|[0-9]+[.)]\\) +\\(\\[X\\]\\)" + 2 'bold prepend) + ;; COMMENT (list (concat "^\\*+[ \t]*\\<\\(" org-comment-string "\\|" org-quote-string "\\)\\>") '(1 'org-special-keyword t)) '("^#.*" (0 'font-lock-comment-face t)) + ;; DONE (if org-fontify-done-headline (list (concat "^[*]+ +\\<\\(" org-done-string "\\)\\(.*\\)\\>") '(1 'org-done t) '(2 'org-headline-done t)) (list (concat "^[*]+ +\\<\\(" org-done-string "\\)\\>") '(1 'org-done t))) + ;; Table stuff '("^[ \t]*\\(:.*\\)" (1 'org-table t)) '("| *\\(:?=[^|\n]*\\)" (1 'org-formula t)) '("^[ \t]*| *\\([#!$*_^]\\) *|" (1 'org-formula t)) @@ -2886,7 +2981,11 @@ between words." ;;; Visibility cycling (defvar org-cycle-global-status nil) +(make-variable-buffer-local 'org-cycle-global-status) (defvar org-cycle-subtree-status nil) +(make-variable-buffer-local 'org-cycle-subtree-status) + +;;;###autoload (defun org-cycle (&optional arg) "Visibility cycling for Org-mode. @@ -2916,15 +3015,17 @@ between words." no headline in line 1, this function will act as if called with prefix arg." (interactive "P") - (if (or (and (bobp) (not (looking-at outline-regexp))) - (equal arg '(4))) - ;; special case: use global cycling - (setq arg t)) + (let* ((outline-regexp + (if org-cycle-include-plain-lists + "\\*+\\|\\([ \t]*\\)\\([-+*]\\|[0-9]+[.)]\\) " + 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))) - (let ((outline-regexp - (if org-cycle-include-plain-lists - "\\*+\\|\\([ \t]*\\)\\([-+*]\\|[0-9]+[.)]\\) " - outline-regexp))) + (if (or bob-special (equal arg '(4))) + ;; special case: use global cycling + (setq arg t)) (cond @@ -2944,18 +3045,8 @@ between words." ;; We just created the overview - now do table of contents ;; This can be slow in very large buffers, so indicate action (message "CONTENTS...") - (save-excursion - ;; Visit all headings and show their offspring - (goto-char (point-max)) - (catch 'exit - (while (and (progn (condition-case nil - (outline-previous-visible-heading 1) - (error (goto-char (point-min)))) - t) - (looking-at outline-regexp)) - (show-branches) - (if (bobp) (throw 'exit nil)))) - (message "CONTENTS...done")) + (org-content) + (message "CONTENTS...done") (setq org-cycle-global-status 'contents) (run-hook-with-args 'org-cycle-hook 'contents)) @@ -2969,7 +3060,7 @@ between words." (t ;; Default action: go to overview - (hide-sublevels 1) + (org-overview) (message "OVERVIEW") (setq org-cycle-global-status 'overview) (run-hook-with-args 'org-cycle-hook 'overview)))) @@ -3042,6 +3133,44 @@ between words." (org-back-to-heading) (org-cycle)))))) +;;;###autoload +(defun org-global-cycle () + "Cycle the global visibility. For details see `org-cycle'." + (interactive) + (org-cycle '(4))) + +(defun org-overview () + "Switch to overview mode, shoing only top-level headlines. +Really, this shows all headlines with level equal or greater than the level +of the first headline in the buffer. This is important, because if the +first headline is not level one, then (hide-sublevels 1) gives confusing +results." + (interactive) + (hide-sublevels (save-excursion + (goto-char (point-min)) + (if (re-search-forward (concat "^" outline-regexp) nil t) + (progn + (goto-char (match-beginning 0)) + (funcall outline-level)) + 1)))) + +;; FIXME: allow an argument to give a limiting level for this. +(defun org-content () + "Show all headlines in the buffer, like a table of contents" + (interactive) + (save-excursion + ;; Visit all headings and show their offspring + (goto-char (point-max)) + (catch 'exit + (while (and (progn (condition-case nil + (outline-previous-visible-heading 1) + (error (goto-char (point-min)))) + t) + (looking-at outline-regexp)) + (show-branches) + (if (bobp) (throw 'exit nil)))))) + + (defun org-optimize-window-after-visibility-change (state) "Adjust the window after a change in outline visibility. This function is the default value of the hook `org-cycle-hook'." @@ -3204,7 +3333,6 @@ or nil." (defvar org-ignore-region nil "To temporarily disable the active region.") -;; FIXME: Fix behavior if point is on the stars but not at bol. (defun org-insert-heading (&optional force-heading) "Insert a new heading or item with same depth at point. If point is in a plain list and FORCE-HEADING is nil, create a new list item. @@ -3218,10 +3346,10 @@ the current headline." (when (or force-heading (not (org-insert-item))) (let* ((head (save-excursion (condition-case nil - (org-back-to-heading) - (error (outline-next-heading))) - (prog1 (match-string 0) - (funcall outline-level)))) + (progn + (org-back-to-heading) + (match-string 0)) + (error "*")))) pos) (cond ((and (org-on-heading-p) (bolp) @@ -3245,10 +3373,14 @@ Return t when things worked, nil when we are not in an item." (org-at-item-p) t) (error nil))) + (debug) (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))) + (checkboxp (save-excursion (goto-char end) + (looking-at "[ \t]*\\[[_X]\\]"))) pos) (cond ((and (org-at-item-p) (<= (point) eow)) @@ -3258,7 +3390,7 @@ Return t when things worked, nil when we are not in an item." ((<= (point) eow) (beginning-of-line 1)) (t (newline))) - (insert bul) + (insert bul (if checkboxp "[_]" "")) (just-one-space) (setq pos (point)) (end-of-line 1) @@ -3618,6 +3750,20 @@ If optional TXT is given, check this string instead of the current kill." ((= llt ?\)) "\\([ \t]*\\([-+]\\|\\([0-9]+)\\)\\)\\|[ \t]+\\*\\)\\( \\|$\\)") (t (error "Invalid value of `org-plain-list-ordered-item-terminator'"))))))) +(defun org-at-item-checkbox-p () + "Is point at a line starting a plain-list item with a checklet?" + (and (org-at-item-p) + (save-excursion + (goto-char (match-end 0)) + (skip-chars-forward " \t") + (looking-at "\\[[_X]\\]")))) + +(defun org-toggle-checkbox () + "Toggle the checkbox in the current line." + (save-excursion + (if (org-at-item-checklet-p) + (replace-match (if (equal (match-string 0) "[_]") "[X]" "[_]") t t)))) + (defun org-get-indentation () "Get the indentation of the current line, interpreting tabs." (save-excursion @@ -3755,7 +3901,7 @@ doing the renumbering." (defun org-renumber-ordered-list (arg) "Renumber an ordered plain list. -Cursor next to be in the first line of an item, the line that starts +Cursor needs to be in the first line of an item, the line that starts with something like \"1.\" or \"2)\"." (interactive "p") (unless (and (org-at-item-p) @@ -4068,35 +4214,35 @@ prefix arg, switch to that state." (member (member this org-todo-keywords)) (tail (cdr member)) (state (cond - ((equal arg '(4)) - ;; Read a state with completion - (completing-read "State: " (mapcar (lambda(x) (list x)) - org-todo-keywords) - nil t)) - ((eq arg 'right) - (if this - (if tail (car tail) nil) - (car org-todo-keywords))) - ((eq arg 'left) - (if (equal member org-todo-keywords) - nil - (if this - (nth (- (length org-todo-keywords) (length tail) 2) - org-todo-keywords) - org-done-string))) - (arg - ;; user requests a specific state - (nth (1- (prefix-numeric-value arg)) - org-todo-keywords)) - ((null member) (car org-todo-keywords)) - ((null tail) nil) ;; -> first entry - ((eq org-todo-interpretation 'sequence) - (car tail)) - ((memq org-todo-interpretation '(type priority)) - (if (eq this-command last-command) - (car tail) - (if (> (length tail) 0) org-done-string nil))) - (t nil))) + ((equal arg '(4)) + ;; Read a state with completion + (completing-read "State: " (mapcar (lambda(x) (list x)) + org-todo-keywords) + nil t)) + ((eq arg 'right) + (if this + (if tail (car tail) nil) + (car org-todo-keywords))) + ((eq arg 'left) + (if (equal member org-todo-keywords) + nil + (if this + (nth (- (length org-todo-keywords) (length tail) 2) + org-todo-keywords) + org-done-string))) + (arg + ;; user requests a specific state + (nth (1- (prefix-numeric-value arg)) + org-todo-keywords)) + ((null member) (car org-todo-keywords)) + ((null tail) nil) ;; -> first entry + ((eq org-todo-interpretation 'sequence) + (car tail)) + ((memq org-todo-interpretation '(type priority)) + (if (eq this-command last-command) + (car tail) + (if (> (length tail) 0) org-done-string nil))) + (t nil))) (next (if state (concat " " state " ") " "))) (replace-match next t t) (setq org-last-todo-state-is-todo @@ -4175,7 +4321,7 @@ of `org-todo-keywords'." A timestamp is also inserted - use \\[org-timestamp-up] and \\[org-timestamp-down] to modify it to the correct date." (interactive) - (org-add-planning-info 'deadline nil nil)) ;; FIXME: remove closed? + (org-add-planning-info 'deadline nil 'closed)) (defun org-schedule () "Insert the SCHEDULED: string to schedule a TODO item. @@ -4191,6 +4337,14 @@ If non is given, the user is prompted for a date. REMOVE indicates what kind of entries to remove. An old WHAT entry will also be removed." (interactive) + (when what (setq time (or time (org-read-date nil 'to-time)))) + (when (and org-insert-labeled-timestamps-at-point + (member what '(scheduled deadline))) + (insert + (if (eq what 'scheduled) org-scheduled-string org-deadline-string) + " " + (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) (org-back-to-heading t) @@ -4234,7 +4388,7 @@ be removed." (if (eq what 'closed) (concat "[" (substring (cdr org-time-stamp-formats) 1 -1) "]") (car org-time-stamp-formats)) - (or time (org-read-date nil 'to-time)))))) + time)))) (goto-char (point-min)) (widen) (if (looking-at "[ \t]+\r?\n") @@ -4254,7 +4408,7 @@ that the match should indeed be shown." (let ((cnt 0)) (save-excursion (goto-char (point-min)) - (hide-sublevels 1) + (org-overview) (while (re-search-forward regexp nil t) (when (or (not callback) (save-match-data (funcall callback))) @@ -4915,7 +5069,6 @@ If there is already a time stamp at the cursor position, update it." (defvar org-agenda-type nil) (defvar org-agenda-force-single-file nil) -;;;###autoload (defun org-agenda-mode () "Mode for time-sorted view on action items in Org-mode files. @@ -5592,7 +5745,7 @@ If ERROR is non-nil, throw an error, otherwise just return nil." (if (memq org-agenda-type types) t (if error - (error "Now allowed in %s-type agenda buffers" org-agenda-type) + (error "Not allowed in %s-type agenda buffers" org-agenda-type) nil))) (defun org-agenda-quit () @@ -6888,7 +7041,7 @@ the same tree node, and the headline of the tree node in the Org-mode file." (beginning-of-line 1))) (defun org-get-tags-at (&optional pos) - "Get a list of all headline targs applicable at POS. + "Get a list of all headline tags applicable at POS. POS defaults to point. If tags are inherited, the list contains the targets in the same sequence as the headlines appear, i.e. the tags of the current headline come last." @@ -6982,6 +7135,7 @@ be used to request time specification in the time stamp." (org-agenda-error))) (buffer (marker-buffer marker)) (pos (marker-position marker)) + (org-insert-labeled-timestamps-at-point nil) ts) (with-current-buffer buffer (widen) @@ -6998,6 +7152,7 @@ be used to request time specification in the time stamp." (org-agenda-error))) (buffer (marker-buffer marker)) (pos (marker-position marker)) + (org-insert-labeled-timestamps-at-point nil) ts) (with-current-buffer buffer (widen) @@ -7177,7 +7332,7 @@ are included in the output." (save-excursion (goto-char (point-min)) - (when (eq action 'sparse-tree) (hide-sublevels 1)) + (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))) @@ -8355,12 +8510,13 @@ For file links, arg negates `org-context-in-file-links'." ((org-region-active-p) (buffer-substring (region-beginning) (region-end))) (t (buffer-substring (point-at-bol) (point-at-eol))))) - (setq cpltxt - (concat cpltxt "::" - (if org-file-link-context-use-camel-case - (org-make-org-heading-camel txt) - (org-make-org-heading-search-string txt))) - desc "NONE"))) + (when (string-match "\\S-" txt) + (setq cpltxt + (concat cpltxt "::" + (if org-file-link-context-use-camel-case + (org-make-org-heading-camel txt) + (org-make-org-heading-search-string txt))) + desc "NONE")))) (if (string-match "::\\'" cpltxt) (setq cpltxt (substring cpltxt 0 -2))) (setq link (org-make-link cpltxt))) @@ -8374,12 +8530,14 @@ For file links, arg negates `org-context-in-file-links'." (setq txt (if (org-region-active-p) (buffer-substring (region-beginning) (region-end)) (buffer-substring (point-at-bol) (point-at-eol)))) - (setq cpltxt - (concat cpltxt "::" - (if org-file-link-context-use-camel-case - (org-make-org-heading-camel txt) - (org-make-org-heading-search-string txt))) - desc "NONE")) + ;; Only use search option if there is some text. + (when (string-match "\\S-" txt) + (setq cpltxt + (concat cpltxt "::" + (if org-file-link-context-use-camel-case + (org-make-org-heading-camel txt) + (org-make-org-heading-search-string txt))) + desc "NONE"))) (setq link (org-make-link cpltxt))) ((interactive-p) @@ -8603,16 +8761,39 @@ is in the current directory or below." ;; URL-like link, normalize the use of angular brackets. (setq link (org-make-link (org-remove-angle-brackets link)))) - ;; Check if we are linking to the current file. If yes, simplify the link. + ;; Check if we are linking to the current file with a search option + ;; If yes, simplify the link by using only the search option. (when (string-match "\\<file:\\(.+?\\)::\\([^>]+\\)" link) (let* ((path (match-string 1 link)) (case-fold-search nil) (search (match-string 2 link))) - (when (save-match-data - (equal (file-truename buffer-file-name) - (file-truename path))) - ;; We are linking to this same file, with a search option - (setq link search)))) + (save-match-data + (if (equal (file-truename buffer-file-name) (file-truename path)) + ;; We are linking to this same file, with a search option + (setq link search))))) + + ;; Check if we can/should use a relative path. If yes, simplify the link + (when (string-match "\\<file:\\(.*\\)" link) + (let* ((path (match-string 1 link)) + (case-fold-search nil)) + (cond + ((eq org-link-file-path-type 'absolute) + (setq path (abbreviate-file-name (expand-file-name path)))) + ((eq org-link-file-path-type 'noabbrev) + (setq path (expand-file-name path))) + ((eq org-link-file-path-type 'relative) + (setq path (file-relative-name path))) + (t + (save-match-data + (if (string-match (concat "^" (regexp-quote + (file-name-as-directory + (expand-file-name ".")))) + (expand-file-name path)) + ;; We are linking a file with relative path name. + (setq path (substring (expand-file-name path) + (match-end 0))))))) + (setq link (concat "file:" path)))) + (setq desc (read-string "Description: " desc)) (unless (string-match "\\S-" desc) (setq desc nil)) (if remove (apply 'delete-region remove)) @@ -8645,7 +8826,7 @@ RET on headline -> Store as sublevel entry to current headline ;;;###autoload (defun org-remember-apply-template () - "Initialize *remember* buffer with template, invode `org-mode'. + "Initialize *remember* buffer with template, invoke `org-mode'. This function should be placed into `remember-mode-hook' and in fact requires to be run from that hook to fucntion properly." (if org-remember-templates @@ -9189,8 +9370,6 @@ With argument TABLE-TYPE, go to the beginning of a table.el-type table." (if table-type org-table-any-border-regexp org-table-border-regexp) nil t)) -; FIXME: OK to just use beginning-of-buffer? - ; (error "Can't find beginning of table") (progn (goto-char (point-min)) (point)) (goto-char (match-beginning 0)) (beginning-of-line 2) @@ -9538,7 +9717,7 @@ If TABLE-TYPE is non-nil, also check for table.el-type tables." "Please position cursor in a data line for column operations"))))) (defun org-table-delete-column () - "Delete a column into the table." + "Delete a column from the table." (interactive) (if (not (org-at-table-p)) (error "Not at a table")) @@ -9677,7 +9856,7 @@ With prefix ARG, insert above the current line." In particular, this does handle wide and invisible characters." (if (string-match "^[ \t]*|-" s) ;; It's a hline, just map the characters - (setq s (mapcar (lambda (x) (if (member x '(?| ?+)) ?| ?\ )) s)) + (setq s (mapconcat (lambda (x) (if (member x '(?| ?+)) "|" " ")) s "")) (while (string-match "|\\([ \t]*?[^ \t\r\n|][^\r\n|]*\\)|" s) (setq s (replace-match (concat "|" (make-string (org-string-width (match-string 1 s)) @@ -10262,7 +10441,7 @@ the current column, to avoid unnecessary parsing." "\n"))) (defun org-table-get-stored-formulas () - "Return an alist with the t=stored formulas directly after current table." + "Return an alist with the stored formulas directly after current table." (interactive) (let (scol eq eq-alist strings string seen) (save-excursion @@ -11179,6 +11358,7 @@ overwritten, and the table is not marked as requiring realignment." (:sub-superscript . org-export-with-sub-superscripts) (:TeX-macros . org-export-with-TeX-macros) (:fixed-width . org-export-with-fixed-width) + (:timestamps . org-export-with-timestamps) (:tables . org-export-with-tables) (:table-auto-headline . org-export-highlight-first-table-line) (:style . org-export-html-style) @@ -11831,6 +12011,19 @@ underlined headlines. The default is 3." (t (insert line "\n")))) (normal-mode) (save-buffer) + ;; remove display and invisible chars + (let (beg end s) + (goto-char (point-min)) + (while (setq beg (next-single-property-change (point) 'display)) + (setq end (next-single-property-change beg 'display)) + (delete-region beg end) + (goto-char beg) + (insert "=>")) + (goto-char (point-min)) + (while (setq beg (next-single-property-change (point) 'org-cwidth)) + (setq end (next-single-property-change beg 'org-cwidth)) + (delete-region beg end) + (goto-char beg))) (goto-char (point-min)))) (defun org-search-todo-below (line lines level) @@ -11910,6 +12103,16 @@ command." (goto-char (org-find-invisible)) (append-to-buffer buffer s (point)) (setq s (goto-char (org-find-visible)))) + (goto-char (point-min)) + (unless keepp + ;; Copy all comment lines to the end, to make sure #+ settings are + ;; still available for the second export step. Kind of a hack, but + ;; does do the trick. + (if (looking-at "#[^\r\n]*") + (append-to-buffer buffer (match-beginning 0) (1+ (match-end 0)))) + (while (re-search-forward "[\n\r]#[^\n\r]*" nil t) + (append-to-buffer buffer (1+ (match-beginning 0)) + (min (point-max) (1+ (match-end 0)))))) (set-buffer buffer) (let ((buffer-file-name file) (org-inhibit-startup t)) @@ -11953,7 +12156,7 @@ Does include HTML export options as well as TODO and CATEGORY stuff." #+CATEGORY: %s #+SEQ_TODO: %s #+TYP_TODO: %s -#+STARTUP: %s %s %s %s %s +#+STARTUP: %s %s %s %s %s %s #+ARCHIVE: %s " (buffer-name) (user-full-name) user-mail-address org-export-default-language @@ -11980,6 +12183,7 @@ Does include HTML export options as well as TODO and CATEGORY stuff." (if org-odd-levels-only "odd" "oddeven") (if org-hide-leading-stars "hidestars" "showstars") (if org-startup-align-all-tables "align" "noalign") + (if org-log-done "logging" "nologging") org-archive-location )) @@ -12378,15 +12582,6 @@ org-mode's default settings, but still inferior to file-local settings." (setq line (replace-match "<span class=\"todo\">\\2</span>" nil nil line 2)))) - ;; DEADLINES - (if (string-match org-deadline-line-regexp line) - (progn - (if (save-match-data - (string-match "<a href" - (substring line 0 (match-beginning 0)))) - nil ; Don't do the replacement - it is inside a link - (setq line (replace-match "<span class=\"deadline\">\\&</span>" - nil nil line 1))))) (cond ((string-match "^\\(\\*+\\)[ \t]*\\(.*\\)" line) ;; This is a headline @@ -12429,14 +12624,15 @@ org-mode's default settings, but still inferior to file-local settings." ;; Normal lines (when (and (string-match (cond - ((eq llt t) "^\\([ \t]*\\)\\(\\([-+*]\\)\\|\\([0-9]+[.)]\\)\\)?\\( +[^ \t\n\r]\\|[ \t]*$\\)") - ((= llt ?.) "^\\([ \t]*\\)\\(\\([-+*]\\)\\|\\([0-9]+\\.\\)\\)?\\( +[^ \t\n\r]\\|[ \t]*$\\)") - ((= llt ?\)) "^\\( \t]*\\)\\(\\([-+*]\\)\\|\\([0-9]+)\\)\\)?\\( +[^ \t\n\r]\\|[ \t]*$\\)") + ((eq llt t) "^\\([ \t]*\\)\\(\\([-+*]\\)\\|\\([0-9]+[.)]\\) \\)?\\( *[^ \t\n\r]\\|[ \t]*$\\)") + ((= llt ?.) "^\\([ \t]*\\)\\(\\([-+*]\\)\\|\\([0-9]+\\.\\) \\)?\\( *[^ \t\n\r]\\|[ \t]*$\\)") + ((= llt ?\)) "^\\( \t]*\\)\\(\\([-+*]\\)\\|\\([0-9]+)\\) \\)?\\( *[^ \t\n\r]\\|[ \t]*$\\)") (t (error "Invalid value of `org-plain-list-ordered-item-terminator'"))) line)) (setq ind (org-get-string-indentation line) start-is-num (match-beginning 4) - starter (if (match-beginning 2) (match-string 2 line)) + starter (if (match-beginning 2) + (substring (match-string 2 line) 0 -1)) line (substring line (match-beginning 5))) (unless (string-match "[^ \t]" line) ;; empty line. Pretend indentation is large. @@ -12646,8 +12842,28 @@ But it has the disadvantage, that Org-mode's HTML conversions cannot be used." (buffer-substring (point-min) (point-max)))) (defun org-html-handle-time-stamps (s) - "FIXME: Format time stamps, or remove them" - 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>" + (match-string 3 s))) + 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))) (defun org-html-protect (s) ;; convert & to &, < to < and > to > @@ -12770,6 +12986,19 @@ When TITLE is nil, just close all open levels." (if org-export-with-section-numbers (setq title (concat (org-section-number level) " " title))) (setq level (+ level 1)) + ;; FIXME: here we need to handle the tags, somehow. + (when (string-match "\\(:[a-zA-Z0-9_@:]+:\\)[ \t]*$" title) + (setq title (replace-match + (if org-export-with-tags + (save-match-data + (concat + " <span class=\"tag\">" + (mapconcat 'identity (org-split-string + (match-string 1 title) ":") + " ") + "</span>")) + "") + t t title))) (if with-toc (insert (format "\n<H%d><a name=\"sec-%d\">%s</a></H%d>\n" level head-count title level)) @@ -12858,7 +13087,7 @@ The XOXO buffer is named *xoxo-<source buffer name>*" (plist-get opt-plist :publishing-directory)) (file-name-sans-extension (file-name-nondirectory buffer-file-name)) - ".xml")) + ".html")) (out (find-file-noselect filename)) (last-level 1) (hanging-li nil)) @@ -13088,6 +13317,7 @@ a time), or the day by one (if it does not contain a time)." ;; Make `C-c C-x' a prefix key (define-key org-mode-map "\C-c\C-x" (make-sparse-keymap)) +(define-key org-mode-map "\C-c\C-e" (make-sparse-keymap)) ;; TAB key with modifiers (define-key org-mode-map "\C-i" 'org-cycle) @@ -13207,6 +13437,15 @@ a time), or the day by one (if it does not contain a time)." (define-key org-mode-map "\C-c\C-x\M-w" 'org-copy-special) (define-key org-mode-map "\C-c\C-x\C-y" 'org-paste-special) +(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) + (when (featurep 'xemacs) (define-key org-mode-map 'button3 'popup-mode-menu)) @@ -13321,7 +13560,7 @@ See the individual commands for more information." (interactive) (cond ((org-at-table-p) (org-table-previous-field)) - (t (org-cycle '(4))))) + (t (org-global-cycle)))) (defun org-shiftmetaleft () "Promote subtree or delete table column. @@ -13523,6 +13762,8 @@ This command does many different things, depending on context: (org-table-recalculate t) (org-table-maybe-recalculate-line)) (org-table-align)) + ((org-at-item-checkbox-p) + (org-toggle-checkbox)) ((org-at-item-p) (org-renumber-ordered-list (prefix-numeric-value arg))) ((save-excursion (beginning-of-line 1) (looking-at "#\\+\\([A-Z]+\\)")) @@ -13711,7 +13952,7 @@ See the individual commands for more information." ["Export visible part..." org-export-visible t] ["HTML" org-export-as-html t] ["HTML and Open" org-export-as-html-and-open t] - ["XML (XOXO)" org-export-as-xml t] + ["XOXO" org-export-as-xml t] "--" ["iCalendar this file" org-export-icalendar-this-file t] ["iCalendar all agenda files" org-export-icalendar-all-agenda-files Binary files differ@@ -1,10 +1,11 @@ \input texinfo + @c %**start of header @setfilename org @c @setfilename ../info/org @settitle Org Mode Manual -@set VERSION 4.29 +@set VERSION 4.30 @set DATE May 2006 @dircategory Emacs @@ -84,6 +85,7 @@ Software Foundation raise funds for GNU development.'' * Tags:: Tagging headlines and matching sets of tags * Agenda views:: Collecting information into views * Exporting:: Sharing and publishing of notes +* Publishing:: * Miscellaneous:: All the rest which did not fit elsewhere * Index:: The fast road to specific information * Key Index:: Key bindings and where they are described @@ -186,7 +188,7 @@ Exporting * ASCII export:: Exporting to plain ASCII * HTML export:: Exporting to HTML -* XML export:: Exporting to XML +* XOXO export:: Exporting to XOXO * iCalendar export:: Exporting in iCalendar format * Text interpretation:: How the exporter looks at the file @@ -196,6 +198,27 @@ Text interpretation by the exporter * Enhancing text:: Subscripts, symbols and more * Export options:: How to influence the export settings +Publishing + +* Configuration:: Defining projects +* Sample configuration:: Example projects +* Triggering publication:: Publication commands + +Configuration + +* Project alist:: The central configuration variable +* File sources and destinations:: From here to there +* Selecting files:: What files are part of the project? +* Publishing action:: +* Publishing options:: Tweaking HTML export +* Links:: Linking between files of a project +* Project page index:: Publishing a list of project files + +Sample configuration + +* Simple example:: One-component publishing +* Complex example:: A multi-component publishing example + Miscellaneous * Completion:: M-TAB knows what you need @@ -209,6 +232,12 @@ Miscellaneous * 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 + @end detailmenu @end menu @@ -241,21 +270,23 @@ Plain text URL-like links connect to websites, emails, Usenet messages, BBDB entries, and any files related to the projects. For printing and sharing of notes, an Org-mode file can be exported as a structured ASCII file, as HTML, or (todo and agenda items only) as an -iCalendar file. +iCalendar file. It can also serve as a publishing tool for a set of +linked webpages. Org-mode keeps simple things simple. When first fired up, it should -feel like a simple, easy to use outliner. Complexity is not imposed, -but a large amount of functionality is available when you need it. -Org-mode can be used on different levels and in different ways, for +feel like a straightforward, easy to use outliner. Complexity is not +imposed, but a large amount of functionality is available when you need +it. Org-mode can be used on different levels and in different ways, for example: @example @r{@bullet{} as an outline extension with visibility cycling and structure editing} @r{@bullet{} as an ASCII system and table editor for taking structured notes} @r{@bullet{} as an ASCII table editor with spreadsheet-like capabilities} -@r{@bullet{} as a simple hypertext system, with HTML export} @r{@bullet{} as a TODO list editor} @r{@bullet{} as a full agenda and planner with deadlines and work scheduling} +@r{@bullet{} as a simple hypertext system, with HTML export} +@r{@bullet{} as a publishing tool to create a set of interlinked webpages} @end example The Org-mode table editor can be integrated into any major mode by @@ -288,19 +319,22 @@ choose suitable keys yourself. (define-key global-map "\C-ca" 'org-agenda) @end lisp -If you have downloaded Org-mode from the Web, you must byte-compile -@file{org.el} and put it on your load path. In addition to the Emacs -Lisp lines above, you also need to add the following lines to +Furthermore, you must activate @code{font-lock-mode} in org-mode +buffers, because significant functionality depends on font-locking being +active. You can do this with either one of the following two lines: +@lisp +(global-font-lock-mode 1) ; for all buffers +(add-hook 'org-mode-hook 'turn-on-font-lock) ; org-mode buffers only +@end lisp + +If you have downloaded Org-mode from the Web, you must take additional +action: Byte-compile @file{org.el} and @file{org-publish.el} and put +them together with @file{org-install.el} on your load path. Then add to @file{.emacs}: @lisp -;; These lines only if org-mode is not part of the X/Emacs distribution. -(autoload 'org-mode "org" "Org mode" t) -(autoload 'org-diary "org" "Diary entries from Org mode") -(autoload 'org-agenda "org" "Multi-file agenda from Org mode" t) -(autoload 'org-store-link "org" "Store a link to the current location" t) -(autoload 'orgtbl-mode "org" "Org tables as a minor mode" t) -(autoload 'turn-on-orgtbl "org" "Org tables as a minor mode") +;; This line only if org-mode is not part of the X/Emacs distribution. +(require 'org-install) @end lisp @cindex org-mode, turning on @@ -407,33 +441,40 @@ starters. @ref{Clean view} describes a setup to realize this. @cindex hide text Outlines make it possible to hide parts of the text in the buffer. -Org-mode uses a single command bound to the @key{TAB} key to change -the visibility in the buffer. +Org-mode uses just two commands, bound to @key{TAB} and +@kbd{S-@key{TAB}} to change the visibility in the buffer. @cindex subtree visibility states +@cindex subtree cycling @cindex folded, subtree visibility state @cindex children, subtree visibility state @cindex subtree, subtree visibility state @table @kbd @kindex @key{TAB} @item @key{TAB} -Rotate current subtree between the states +@emph{Subtree cycling}: Rotate current subtree between the states @example ,-> FOLDED -> CHILDREN -> SUBTREE --. '-----------------------------------' @end example -At the beginning of the buffer (or when called with @kbd{C-u}), this does -the same as the command @kbd{S-@key{TAB}} below. +The cursor must be on a headline for this to work@footnote{see, however, +the option @code{org-cycle-emulate-tab}.}. When the cursor is at the +beginning of the buffer and the first line is not a headline, then +@key{TAB} actually runs global cycling (see below)@footnote{see the +option @code{org-cycle-global-at-bob}.}. Also when called with a prefix +argument (@kbd{C-u @key{TAB}}), global cycling is invoked. @cindex global visibility states +@cindex global cycling @cindex overview, global visibility state @cindex contents, global visibility state @cindex show all, global visibility state @kindex S-@key{TAB} @item S-@key{TAB} -Rotate the entire buffer between the states +@itemx C-u @key{TAB} +@emph{Global cycling}: Rotate the entire buffer between the states @example ,-> OVERVIEW -> CONTENTS -> SHOW ALL --. @@ -694,9 +735,22 @@ But in the end, not individual scenes matter but the film as a whole. @end example Org-mode supports these lists by tuning filling and wrapping commands -to correctly deal with them. Furthermore, the following commands act -on items when the cursor is in the first line of an item (the line -with the bullet or number). +to correctly deal with them. + +@cindex checkboxes +Every item in a plain list can be made a checkbox by starting it with +the string @samp{[_]}. The checkbox status can conveniently be toggled +with @kbd{C-c C-c}. + +@example +* Shopping list + - [_] Milk + - [X] Butter + - [_] bred +@end example + +The following commands act on items when the cursor is in the first line +of an item (the line with the bullet or number). @table @kbd @kindex @key{TAB} @@ -715,7 +769,8 @@ item. If this command is executed in the @emph{whitespace before a bullet or number}, the new item is created @emph{before} the current item. If the command is executed in the white space before the text that is part of an item but does not contain the bullet, a bullet is added to the -current line. +current line. If the current item has a checkbox, so will the newly +created item. @kindex M-S-@key{up} @kindex M-S-@key{down} @item M-S-@key{up} @@ -735,7 +790,9 @@ would imply a different hierarchy. To use the new hierarchy, break the command chain with a cursor motion or so. @kindex C-c C-c @item C-c C-c -Renumber the ordered list at the cursor. +If there is a checkbox in the item line, toggle the state of the +checkbox. Otherwise, if this is an ordered list, renumber the ordered +list at the cursor. @end table @node Tables, Hyperlinks, Document structure, Top @@ -954,7 +1011,7 @@ When not empty, copy current field down to next row and move cursor along with it. Depending on the variable @code{org-table-copy-increment}, integer field values will be incremented during copy. This key is also used by CUA-mode -(@pxref{Interaction}). +(@pxref{Cooperation}). @tsubheading{Miscellaneous} @kindex C-c ` @@ -1389,7 +1446,7 @@ possible. @chapter Hyperlinks @cindex hyperlinks -Just like HMTL, Org-mode provides links inside a file, and external +Just like HTML, Org-mode provides links inside a file, and external links to other files, Usenet articles, emails and much more. @menu @@ -1605,7 +1662,9 @@ that you don't have to use this command to insert a link. Links in Org-mode are plain text, and you can type or paste them straight into the buffer. By using this command, the links are automatically enclosed in double brackets, and you will be asked for the optional descriptive -text. +text. If the link is a @samp{file:} link and the linked file is located +in the same directory as the current file or a subdirectory of it, the +path of the file will be inserted relative to the current directory. @kindex C-u C-c C-l @cindex file name completion @@ -1749,19 +1808,14 @@ store quick notes with little interruption of your work flow. See @uref{http://www.emacswiki.org/cgi-bin/wiki/RememberMode} for more information. The notes produced by @emph{Remember} can be stored in different ways, and Org-mode files are a good target. Org-mode allows -to file away notes either to a default file, or directly to the -correct location in your Org-mode outline tree. The following -customization@footnote{The three autoload forms are only necessary if -@file{org.el} is not part of the Emacs distribution or an XEmacs -package.} will tell @emph{Remember} to use org files as target, and to -create annotations compatible with Org-mode links. +to file away notes either to a default file, or directly to the correct +location in your Org-mode outline tree. The following customization +will tell @emph{Remember} to use org files as target, and to create +annotations compatible with Org-mode links. @example (setq org-directory "~/path/to/my/orgfiles/") (setq org-default-notes-file "~/.notes") -(autoload 'org-remember-annotation "org") -(autoload 'org-remember-apply-template "org") -(autoload 'org-remember-handler "org") (setq remember-annotation-functions '(org-remember-annotation)) (setq remember-handler-functions '(org-remember-handler)) (add-hook 'remember-mode-hook 'org-remember-apply-template) @@ -2081,7 +2135,7 @@ agenda buffer with the @kbd{,} command (@pxref{Agenda commands}). Increase/decrease priority of current item. Note that these keys are also used to modify time stamps (@pxref{Creating timestamps}). Furthermore, these keys are also used by CUA-mode -(@pxref{Interaction}). +(@pxref{Conflicts}). @end table @node Timestamps, Tags, TODO items, Top @@ -2225,7 +2279,7 @@ Insert @samp{SCHEDULED} keyword along with a stamp. @item S-@key{left} @itemx S-@key{right} Change date at cursor by one day. These key bindings conflict with -CUA-mode (@pxref{Interaction}). +CUA-mode (@pxref{Conflicts}). @kindex S-@key{up} @kindex S-@key{down} @@ -2235,7 +2289,7 @@ Change the item under the cursor in a timestamp. The cursor can be on a year, month, day, hour or minute. Note that if the cursor is not at a time stamp, these same keys modify the priority of an item. (@pxref{Priorities}). The key bindings also conflict with CUA-mode -(@pxref{Interaction}). +(@pxref{Conflicts}). @kindex C-c C-y @@ -2978,14 +3032,14 @@ visit org files will not be removed. @end table -@node Exporting, Miscellaneous, Agenda views, Top +@node Exporting, Publishing, Agenda views, Top @chapter Exporting @cindex 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 simple version of an Org-mode file. HTML export allows to publish a -notes file on the web, while the XML format provides a solid base for +notes file on the web, while the XOXO format provides a solid base for exchange with a broad range of other applications. To incorporate entries with associated times like deadlines or appointments into a desktop calendar program like iCal, Org-mode can also produce extracts @@ -2998,7 +3052,7 @@ produced. @xref{Text interpretation}, for more details. @menu * ASCII export:: Exporting to plain ASCII * HTML export:: Exporting to HTML -* XML export:: Exporting to XML +* XOXO export:: Exporting to XOXO * iCalendar export:: Exporting in iCalendar format * Text interpretation:: How the exporter looks at the file @end menu @@ -3038,7 +3092,7 @@ at a different level, specify it with a prefix argument. For example, @noindent creates only top level headlines and does the rest as items. -@node HTML export, XML export, ASCII export, Exporting +@node HTML export, XOXO export, ASCII export, Exporting @section HTML export @cindex HTML export @@ -3081,7 +3135,20 @@ mark them with a @samp{@@} like in @samp{@@<b>bold text@@</b>}. Plain @samp{<} and @samp{>} are always transformed to @samp{<} and @samp{>} in HTML export. -You can also give style information for the exported file. The +You can also give style information for the exported file. The HTML +exporter asigns the following CSS classes to appropriate parts of the +document - your style specifications may change these. +@example +.todo @r{TODO keywords} +.done @r{the DONE keyword} +.timestamp @r{time stamp} +.timestamp-kwd @r{keyword associated with a time stamp, like SCHEDULED} +.tag @r{tag in a headline} +.target @r{target for links} +@end example + + +The default specification can be configured through the option @code{org-export-html-style}. If you want to use a file-local style, you may use file variables, best wrapped into a COMMENT section at the @@ -3106,24 +3173,24 @@ section in the buffer. @c FIXME: More about header and footer styles @c FIXME: Talk about links and targets. -@node XML export, iCalendar export, HTML export, Exporting -@section XML export -@cindex XML export +@node XOXO export, iCalendar export, HTML export, Exporting +@section XOXO export +@cindex XOXO export -Org-mode contains an XML exporter that produces XOXO-style XML. +Org-mode contains an exporter that produces XOXO-style output. Currently, this exporter only handles the general outline structure and does not interpret any additional Org-mode features. @table @kbd @kindex C-c C-x C-x @item C-c C-x C-x -Export as XML file @file{myfile.xml}. +Export as XOXO file @file{myfile.html}. @kindex C-c C-x v @item C-c C-x v x Export only the visible part of the document. @end table -@node iCalendar export, Text interpretation, XML export, Exporting +@node iCalendar export, Text interpretation, XOXO export, Exporting @section iCalendar export @cindex iCalendar export @@ -3322,7 +3389,313 @@ toc: @r{turn on/off table of contents} TeX: @r{turn on/off @TeX{} macros} @end example -@node Miscellaneous, Index, Exporting, Top +@node Publishing, Miscellaneous, Exporting, Top +@chapter 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 +need to download this file separately. Also make sure org.el is at +least version 4.27.} a publishing management system +that allows you to configure automatic html conversion of +@emph{projects} composed of interlinked org files. This system is +called @emph{org-publish}. You can also configure org-publish to +automatically upload your exported HTML pages and related attachments, +such as images and source code files, to a web server. Org-publish turns +org-mode into a web-site authoring tool. + +Org-publish has been contributed to Org-mode by David O'Toole. + +@menu +* Configuration:: Defining projects +* Sample configuration:: Example projects +* Triggering publication:: Publication commands +@end menu + +@node Configuration, Sample configuration, Publishing, Publishing +@section Configuration + +Publishing needs significant configuration to specify files, destination +and many other properties of a project. + +@menu +* Project alist:: The central configuration variable +* File sources and destinations:: From here to there +* Selecting files:: What files are part of the project? +* Publishing action:: +* Publishing options:: Tweaking HTML export +* Links:: Linking between files of a project +* Project page index:: Publishing a list of project files +@end menu + +@node Project alist, File sources and destinations, Configuration, Configuration +@subsection The variable @code{org-publish-project-alist} + +Org-publish is configured almost entirely through setting the value of +one variable, called @code{org-publish-project-alist}. +Each element of the list configures one project, and may be in one of +the two following forms: + +@lisp +("project-name" :property value :property value ...) + +@r{or} + +("project-name" + ("component1" :property value :property value ...) + ("component2" :property value :property value ...) + ...) +@end lisp + +In both cases, projects are configured by specifying property values. +A project defines the set of files that will be published, as well as +the publishing configuration to use when publishing those files. +When a project takes the second form listed above, the individual +property lists are taken to be "components" of the project, which +group together files requiring different publishing options. + +@node File sources and destinations, Selecting files, Project alist, Configuration +@subsection Sources and destinations for files + +Most properties are optional, but some should always be set. In +particular, org-publish needs to know where to look for source files, +and where to put published files. + +@multitable @columnfractions 0.3 0.7 +@item @code{:base-directory} +@tab Directory containing publishing source files +@item @code{:publishing-directory} +@tab Directory (possibly remote) where output files will be published. +@end multitable +@noindent + +@node Selecting files, Publishing action, File sources and destinations, Configuration +@subsection Selecting files + +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 +properties +@multitable @columnfractions 0.25 0.75 +@item @code{:base-extension} +@tab Extension (without the dot!) of source files. This actually is a +regular expression. + +@item @code{:exclude} +@tab Regular expression to match file names that should not be +published, even though they have been selected on the basis of their +extension. + +@item @code{:include} +@tab List of files to be included regardless of @code{:base-extension} +and @code{:exclude}. +@end multitable + +@node Publishing action, Publishing options, Selecting files, Configuration +@subsection Publishing Action + +Publishing means that a file is copied to the destination directory and +possibly transformed in the process. The default transformation is to +export Org-mode files as HTML files, and this is done by the function +@code{org-publish-org-to-html} which calls the HTML exporter +(@pxref{HTML export}). Other files like images only need to be copied +to the publishing destination. For non-Org-mode files, you need to +specify the publishing function. + +@multitable @columnfractions 0.3 0.7 +@item @code{:publishing-function} +@tab Function executing the publication of a file. +@end multitable + +The function must accept two arguments: a property list containing at +least a @code{:publishing-directory} property, and the name of the file +to be published. I should take the specified file, make the necessary +transformation (if any) and place the result into the destination folder. +You can write your own publishing function, but @code{org-publish} +provides one for attachments (files that only need to be copied): +@code{org-publish-attachment}. + +@node Publishing options, Links, Publishing action, Configuration +@subsection Options for the HTML exporter + +The property list can be used to set many export options for the HTML +exporter. In most cases, these properties correspond to user variables +in Org-mode. The table below lists these properties along with the +variable they belong to. See the documentation string for the +respective variable for details. + +@multitable @columnfractions 0.3 0.7 +@item @code{:language} @tab @code{org-export-default-language} +@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{: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{: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} +@item @code{:tables} @tab @code{org-export-with-tables} +@item @code{:table-auto-headline} @tab @code{org-export-highlight-first-table-line} +@item @code{:style} @tab @code{org-export-html-style} +@item @code{:convert-org-links} @tab @code{org-export-html-link-org-files-as-html} +@item @code{:inline-images} @tab @code{org-export-html-inline-images} +@item @code{:expand-quoted-html} @tab @code{org-export-html-expand} +@item @code{:timestamp} @tab @code{org-export-html-with-timestamp} +@item @code{:publishing-directory} @tab @code{org-export-publishing-directory} +@item @code{:preamble} @tab @code{org-export-html-preamble} +@item @code{:postamble} @tab @code{org-export-html-postamble} +@item @code{:auto-preamble} @tab @code{org-export-html-auto-preamble} +@item @code{:auto-postamble} @tab @code{org-export-html-auto-postamble} +@item @code{:author} @tab @code{user-full-name} +@item @code{:email} @tab @code{user-mail-address} +@end multitable + +When a property is given a value in org-publish-project-alist, its +setting overrides the value of the corresponding user variable (if any) +during publishing. However, options set within a file (@pxref{Export +options}) override everything. + +@node Links, Project page index, Publishing options, Configuration +@subsection Links between published files + +To create a link from one Org-mode file to another, you would use +something like @samp{[[file:foo.org][The foo]]} or simply +@samp{file:foo.org.} (@pxref{Hyperlinks}). Upon publishing this link +becomes a link to @file{foo.html}. In this way, you can interlink the +pages of your "org web" project and the links will work as expected when +you publish them to HTML. + +You may also link to related files, such as images. Provided you are +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. + +@node Project page index, , Links, Configuration +@subsection Project page index + +The following properties may be used to control publishing of an +index of files or summary page for a given project. + +@multitable @columnfractions 0.25 0.75 +@item @code{:auto-index} +@tab When non-nil, publish an index during org-publish-current-project or +org-publish-all. + +@item @code{:index-filename} +@tab Filename for output of index. Defaults to @file{index.org} (which +becomes @file{index.html}). + +@item @code{:index-title} +@tab Title of index page. Defaults to name of file. + +@item @code{:index-function} +@tab Plugin function to use for generation of index. +Defaults to @code{org-publish-org-index}, which generates a plain list +of links to all files in the project. +@end multitable + +@node Sample configuration, Triggering publication, Configuration, Publishing +@section Sample configuration + +Below we provide two example configurations. The first one is a simple +project publishing only a set of Org-mode files. The second example is +more complex, with a multi-component project. + +@menu +* Simple example:: One-component publishing +* Complex example:: A multi-component publishing example +@end menu + +@node Simple example, Complex example, Sample configuration, Sample configuration +@subsection Example: simple publishing configuration + +This example publishes a set of Org-mode files to the @file{public_html} +directory on the local machine. + +@lisp +(setq org-publish-project-alist + '(("org" + :base-directory "~/org/" + :publishing-directory "~/public_html" + :section-numbers nil + :table-of-contents nil + :style "<link rel=stylesheet + href=\"../other/mystyle.css\" + type=\"text/css\">"))) +@end lisp + +@node Complex example, , Simple example, Sample configuration +@subsection Example: complex publishing configuration + +This more complicated example publishes an entire website, including +org files converted to HTML, image files, emacs lisp source code, and +stylesheets. The publishing-directory is remote and private files are +excluded. + +To ensure that links are preserved, care should be taken to replicate +your directory structure on the web server, and to use relative file +paths. For example, if your org files are kept in @file{~/org} and your +publishable images in @file{~/images}, you'd link to an image with +@c +@example +file:../images/myimage.png +@end example +@c +On the web server, the relative path to the image should be the +same. You can accomplish this by setting up an "images" folder in the +right place on the webserver, and publishing images to it. + +@lisp +(setq org-publish-project-alist + '(("website" + ("orgfiles" + :base-directory "~/org/" + :base-extension "org" + :publishing-directory "/ssh:user@@host:~/html/notebook/" + :publishing-function org-publish-org-to-html + :exclude "PrivatePage.org" ;; regexp + :headline-levels 3 + :section-numbers nil + :table-of-contents nil + :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\\|el" + :publishing-directory "/ssh:user@@host:~/html/other/" + :publishing-function org-publish-attachment)))) +@end lisp + +@node Triggering publication, , Sample configuration, Publishing +@section Triggering publication + +Once org-publish is properly configured, you can publish with the +following functions: + +@table @kbd +@item C-c C-e c +Prompts for a specific project to publish. +@item C-c C-e p +Publishes the project the current file is part of. +@item C-c C-e f +Publishes only the current file. +@item C-c C-e a +Publish all projects. +@end table + +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 @chapter Miscellaneous @menu @@ -3431,6 +3804,12 @@ variable is @code{org-startup-align-all-tables}, with a default value align @r{align all tables} noalign @r{don't align tables on startup} @end example +Logging when a TODO item is marked DONE (variable @code{org-log-done}) +can be configured using these options. +@example +logging @r{record a timestamp when an item is marked DONE} +nologging @r{don't record when items are marked DONE} +@end example Here are the options for hiding leading stars in outline headings. The corresponding variables are @code{org-hide-leading-stars} and @code{org-odd-levels-only}, both with a default setting @code{nil} @@ -3473,14 +3852,14 @@ this means in different contexts. @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 the cursor is in one of the special #+KEYWORD lines, this +If the cursor is in one of the special @code{#+KEYWORD} lines, this triggers scanning the buffer for these lines and updating the information. @item If the cursor is inside a table, realign the table. This command works even if the automatic table editor has been turned off. @item -If the cursor is on a #+TBLFM line, re-apply the formulas to +If the cursor is on a @code{#+TBLFM} line, re-apply the formulas to the entire table. @item If the cursor is inside a table created by the @file{table.el} package, @@ -3490,8 +3869,11 @@ If the current buffer is a remember buffer, close note and file it. with a prefix argument, file it without further interaction to the default location. @item -If the cursor is on a <<<target>>>, update radio targets and corresponding -links in this buffer. +If the cursor is on a @code{<<<target>>>}, update radio targets and +corresponding links in this buffer. +@item +If the cursor is in a plain list item with a checkbox, toggle the status +of the checkbox. @item If the cursor is on a numbered item in a plain list, renumber the ordered list. @@ -3640,27 +4022,50 @@ rather use @kbd{C-c .} to re-insert the timestamp. @cindex FAQ @enumerate - -@cindex allout.el, conflict with @cindex @code{keymapp nil} error @item @b{When I try to use Org-mode, I always get @code{(wrong-type-argument keymapp nil)}}.@* -This is a conflict with an outdated version of the @file{allout.el} -package which pretends to be also the standard outline-mode but is not. -This happens with older versions of @file{allout.el}, for example the -one distributed with Emacs 21. Upgrade to Emacs 22 and this problem -will disappear. If for some reason you cannot do this, make sure that -org.el is loaded @emph{before} @file{allout.el}, for example by putting -@code{(require 'org)} early enough into your @file{.emacs} file. +@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?} -@c @* -@example +@lisp (add-to-list 'auto-mode-alist '("README$" . org-mode)) -@end example +@end lisp + +@item @b{I would like to use editing features of org-mode in other +modes, is his 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?}@* @@ -3690,7 +4095,7 @@ Would I let you down like that? If you must, you can do this @end lisp @item @b{When I am executing shell links I always get a -confirmation prompt and need to type @kbd{yes @key{RET}}, thats 4 key +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 @@ -3753,7 +4158,7 @@ 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{Interaction}. +Yes, see @ref{Conflicts}. @item @b{One of my table columns has started to fill up with @samp{#ERROR}. What is going on?}@* @@ -3784,10 +4189,8 @@ emacs diary?}@* 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. The following steps are necessary: -Autoload the function @command{org-diary} as shown above under -@ref{Installation and activation}. You also need to use @emph{fancy -diary display} by setting in @file{.emacs}: +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) @@ -3823,20 +4226,50 @@ the agenda buffer. @node Interaction, Bugs, FAQ, Miscellaneous @section Interaction with other packages @cindex packages, interaction with other -Org-mode can cooperate with the following packages: +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-checklet.el} +@item @file{org-checklet.el} by Frank Ruell +Provides checklist of items which can be either checked or unchecked. +This is similar to the TODO functionality in Org-mode, but never shows +up in the agenda. @file{org-checklet} is freely available at +@url{http://www.emacswiki.org/cgi-bin/emacs/org-checklet.el}. @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. -Use a search engine to find this package on the web. -@cindex @file{table.el} -@item @file{table.el} by Takaaki Ota -Org mode cooperates with table.el, see @ref{table.el}. @file{table.el} -is part of Emacs 22. +@file{org-mouse.el} is freely avaliable 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. However, it is not yet part of Emacs 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 +@subsection Packages that Org-mode cooperates with + +@table @asis @cindex @file{calc.el} @item @file{calc.el} by Dave Gillespie Org-mode uses the calc package for implementing spreadsheet @@ -3859,6 +4292,31 @@ 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{remember.el} by John Wiegley +@cindex @file{remember.el} +Org mode cooperates with remember, see @ref{Remember}. +@file{Remember.el} is not part of Emacs, find it on the web. +@cindex @file{table.el} +@item @file{table.el} by Takaaki Ota +Org mode cooperates with table.el, see @ref{table.el}. @file{table.el} +is part of Emacs 22. +@end table + +@node Conflicts, , Cooperation, Interaction +@subsection Packages that lead to conflicts with Org-mode + +@table @asis + +@cindex @file{allout.el} +@item @file{allout.el} by Ken Manheimer +Startup of Org-mode may fail with the error message +@code{(wrong-type-argument keymapp nil)} when there is an outdated +version @file{allout.el} on the load path, for example the version +distributed with Emacs 21.x. Upgrade to Emacs 22 and this problem will +disappear. If for some reason you cannot do this, make sure that org.el +is loaded @emph{before} @file{allout.el}, for example by putting +@code{(require 'org)} early enough into your @file{.emacs} file. + @cindex @file{CUA.el} @item @file{CUA.el} by Kim. F. Storm Keybindings in Org-mode conflict with the @kbd{S-<cursor>} keys @@ -3882,12 +4340,9 @@ to have other replacement keys, look at the variable @cindex @file{windmove.el} Also this package uses the @kbd{S-<cursor>} keys, so everything written in the paragraph above about CUA mode also applies here. -@item @file{remember.el} by John Wiegley -@cindex @file{remember.el} -Org mode cooperates with remember, see @ref{Remember}. -@file{Remember.el} is not part of Emacs, find it on the web. @end table + @node Bugs, Acknowledgments, Interaction, Miscellaneous @section Bugs @cindex bugs @@ -3911,7 +4366,7 @@ Text in an entry protected with the @samp{QUOTE} keyword should not autowrap. @item When the application called by @kbd{C-c C-o} to open a file link fails -(for example because the application does not exits or refuses to open +(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 @@ -3927,9 +4382,8 @@ 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 -You can only make a single word boldface or italic. To emphasize -several words in a row, each must have the emphasize markers, like in -@samp{*three* *bold* *words*}. +Several words in a rom may @b{*be made bold*}, but this does not work if +the string is distributed over two lines. @item The exporters work well, but could be made more efficient. @end itemize diff --git a/orgcard.pdf b/orgcard.pdf Binary files differindex 94bc0ef..9e9d926 100644 --- a/orgcard.pdf +++ b/orgcard.pdf diff --git a/orgcard.tex b/orgcard.tex index 6c5b5ab..72fccaa 100644 --- a/orgcard.tex +++ b/orgcard.tex @@ -1,5 +1,5 @@ % Reference Card for Org Mode -\def\orgversionnumber{4.29} +\def\orgversionnumber{4.30} \def\year{2006} % %**start of header @@ -269,19 +269,11 @@ are preserved on all copies. \section{Getting Started} % -%Put the following in your \kbd{~/.emacs}$^1$ \vskip -1mm \beginexample% -%(autoload 'org-mode "org" "Org mode" t) -%(autoload 'org-diary "org" "Org mode diary entries") -%(autoload 'org-agenda "org" "Agenda from Org files" t) -%(autoload 'org-todo-list "org" "Global TODO list" t) -%(autoload 'org-store-link "org" "Store org link" t) -%(autoload 'orgtbl-mode "org" "Orgtbl minor mode" t) -%(autoload 'turn-on-orgtbl "org" "Orgtbl minor mode") (add-to-list 'auto-mode-alist '("\\\\.org\$" . org-mode)) -(define-key global-map "\\C-cl" 'org-store-link)$^2$ -(define-key global-map "\\C-ca" 'org-agenda)$^2$ +(define-key global-map "\\C-cl" 'org-store-link)$^1$ +(define-key global-map "\\C-ca" 'org-agenda)$^1$ \endexample % \metax{For the many customization options try}{M-x org-customize} @@ -320,7 +312,7 @@ are preserved on all copies. \key{yank subtree}{C-c C-x C-y} \key{archive subtree}{C-c \$} -To set archive location for current file, add a line like$^3$: +To set archive location for current file, add a line like$^2$: \vskip -1mm \beginexample% \#+ARCHIVE: archfile::* Archived Tasks @@ -330,10 +322,10 @@ To set archive location for current file, add a line like$^3$: \key{show sparse tree for all matches of a regexp}{C-c /} \key{view TODO's in sparse tree}{C-c C-v} -\key{global TODO list in agenda mode}{C-c t$^2$} +\key{global TODO list in agenda mode}{C-c t$^1$} \key{create sparse tree with all deadlines due}{C-c C-w} \key{time sorted view of current org file}{C-c C-r} -%\key{agenda for the week}{C-c a$^2$} +%\key{agenda for the week}{C-c a$^1$} %\key{agenda for date at cursor}{C-c C-o} \section{Tags} @@ -351,8 +343,8 @@ To set archive location for current file, add a line like$^3$: \key{set the priority of the current item}{C-c , [ABC]} \key{remove priority cookie from current item}{C-c , SPC} -\key{raise priority of current item}{S-UP$^4$} -\key{lower priority of current item}{S-DOWN$^4$} +\key{raise priority of current item}{S-UP$^3$} +\key{lower priority of current item}{S-DOWN$^3$} \key{\kbd{\#+SEQ_TODO: TODO TRY BLUFF DONE}}{\rm todo workflow} \key{\kbd{\#+TYP_TODO: Phil home work DONE}}{\rm todo types} @@ -366,8 +358,8 @@ To set archive location for current file, add a line like$^3$: \key{insert SCHEDULED timestamp}{C-c C-s} \key{create sparse tree with all deadlines due}{C-c C-w} \key{the time between 2 dates in a time range}{C-c C-y} -\key{change timestamp at cursor by $\pm 1$ day}{S-RIGHT/LEFT$^4$} -\key{change year/month/day at cursor by $\pm 1$}{S-UP/DOWN$^4$} +\key{change timestamp at cursor by $\pm 1$ day}{S-RIGHT/LEFT$^3$} +\key{change year/month/day at cursor by $\pm 1$}{S-UP/DOWN$^3$} \key{access the calendar for the current date}{C-c >} \key{insert timestamp matching date in calendar}{C-c <} \key{access agenda for current date}{C-c C-o} @@ -380,7 +372,7 @@ To set archive location for current file, add a line like$^3$: \section{Links} -\key{globally store link to the current location}{C-c l$^2$} +\key{globally store link to the current location}{C-c l$^1$} \key{insert a link (TAB completes stored links)}{C-c C-l} \key{insert file link with file name completion}{C-u C-c C-l} \key{edit (also hidden part of) link at point}{C-c C-l} @@ -394,7 +386,7 @@ To set archive location for current file, add a line like$^3$: {\bf Internal Links} \key{\kbd{<<My Target>>}}{\rm target} -\key{\kbd{<<<My Target>>>}}{\rm radio target$^3$} +\key{\kbd{<<<My Target>>>}}{\rm radio target$^2$} \key{\kbd{[[*this text]]}}{\rm find headline} \metax{\kbd{[[this text]]}}{\rm find target or text in buffer} \metax{\kbd{[[this text][description]]}}{\rm optional link text} @@ -479,7 +471,7 @@ Outside of tables, the same keys may have other functionality. \key{display column number cursor is in}{C-c ?} \key{sum numbers in current column/rectangle}{C-c +} -\key{copy down with increment}{S-RET$^4$} +\key{copy down with increment}{S-RET$^3$} Formulas typed in field are executed by \kbd{TAB}, \kbd{RET} and \kbd{C-c C-c}. \kbd{=} introduces a column @@ -516,15 +508,15 @@ formula, \kbd{:=} a named-field formula. \key{remove current file from your agenda}{C-c ]} \key{cycle through agenda file list}{C-,} -\key{compile agenda for the current week}{C-c a a$^2$} -\key{compile global TODO list}{C-c a t$^2$} -\key{compile TODO list for specific keyword}{C-c a T$^2$} -\key{match tags in agenda files}{C-c a m$^2$} +\key{compile agenda for the current week}{C-c a a$^1$} +\key{compile global TODO list}{C-c a t$^1$} +\key{compile TODO list for specific keyword}{C-c a T$^1$} +\key{match tags in agenda files}{C-c a m$^1$} \key{agenda for date at cursor}{C-c C-o} \key{show timeline of current org file}{C-c C-r} \vskip 1mm -To set categories, add lines like$^3$: +To set categories, add lines like$^2$: \vskip -1mm \beginexample% \#+CATEGORY: MyCateg @@ -561,10 +553,10 @@ To set categories, add lines like$^3$: \key{show tags of current headline}{T} \key{set tags for current headline}{:} \key{set priority of current item}{p} -\key{raise/lower priority of current item}{S-UP/DOWN$^4$} +\key{raise/lower priority of current item}{S-UP/DOWN$^3$} \key{display weighted priority of current item}{P} \key{schedule/set deadline for this item}{C-c C-s/d} -\key{change timestamp to one day earlier/later}{S-LEFT/RIGHT$^4$} +\key{change timestamp to one day earlier/later}{S-LEFT/RIGHT$^3$} \key{change timestamp to today}{>} \key{insert new entry into diary}{i} @@ -627,8 +619,6 @@ keywords. {\tt M-TAB} again just after keyword is complete inserts examples. \key{... which can carry over multiple lines}{\#+TEXT:} \key{settings for the export process - see below}{\#+OPTIONS:} -{\bf Settings for the OPTIONS line} - \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} @@ -649,6 +639,13 @@ Subtrees whose header starts with COMMENT are never exported. \key{toggle COMMENT keyword on entry}{C-c ;} + +\section{Publishing (requires org-publish.el)} +\key{publishcurrent file}{C-c C-e C-f} +\key{publish current project}{C-c C-e C-p} +\key{publish project (prompted for)}{C-c C-e C-c} +\key{publish all projects}{C-c C-e C-a} + \section{Completion} In-buffer completion completes TODO keywords at headline start, TeX @@ -657,8 +654,6 @@ after ``{\tt :}'', and dictionary words elsewhere. \key{Complete word at point}{M-TAB} -\newcolumn - \section{Calendar and Diary Integration} To include entries from the Emacs diary in your Org-mode agenda: @@ -666,26 +661,6 @@ To include entries from the Emacs diary in your Org-mode agenda: (setq org-agenda-include-diary t) \endexample -To include the Org-mode agenda in the normal diary, make sure you're -using the fancy diary display -% -%\beginexample% -%(add-hook 'diary-display-hook 'fancy-diary-display) -%\endexample -% -and in the \kbd{~/diary} file add - -\beginexample% -\&\%\%(org-diary) -\endexample - -to include all the files listed in \kbd{org-agenda-files}. For more -selective file inclusion use a line for each file: - -\beginexample% -\&\%\%(org-diary) ~/path/to/some/org-file.org -\endexample - \section{Remember-mode Integration} See the manual for how to make remember.el use Org-mode links and @@ -710,7 +685,7 @@ Insert the note with one of the following: 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$^4$ +buffer, but not during date selection). See note mark four$^3$ throughout the reference card. %\vskip-mm \beginexample @@ -720,16 +695,13 @@ S-RET $\to$ C-S-RET \endexample \section{Notes} -$^1$ The six autoload forms are only needed if Org-mode is not part of -Emacs, or an XEmacs package. - -$^2$ This is only a suggestion for a binding of this command. Choose +$^1$ This is only a suggestion for a binding of this command. Choose you own key as shown under INSTALLATION. -$^3$ After changing a \kbd{\#+KEYWORD} or \kbd{<<<target>>>} line, +$^2$ After changing a \kbd{\#+KEYWORD} or \kbd{<<<target>>>} line, press \kbd{C-c C-c} with the cursor still in the line to update. -$^4$ Keybinding affected by {\tt org-CUA-compatibility}. +$^3$ Keybinding affected by {\tt org-CUA-compatibility}. \copyrightnotice |