(Fnext_char_property_change)
(Fprevious_char_property_change): allow marker as limit.
(Fnext_single_char_property_change)
(Fprevious_single_char_property_change): Check that limit is a
number in strings.
(Fnext_single_char_property_change): Coerce position to integer.
(Fprevious_single_char_property_change): Same here.
\input texinfo@c %**start of header@setfilename ../info/org@settitle Org Mode Manual@set VERSION 3.04@set DATE December 2004@dircategory Emacs@direntry* Org Mode: (org). Outline-based notes management and organizer @end direntry@c Version and Contact Info@set MAINTAINERSITE @uref{http://www.astro.uva.nl/~dominik/Tools/org/,maintainers webpage}@set MAINTAINER Carsten Dominik@set MAINTAINEREMAIL @email{dominik@@science.uva.nl}@set MAINTAINERCONTACT @uref{mailto:dominik@@science.uva.nl,contact the maintainer}@c %**end of header@finalout@c Macro definitions@c Subheadings inside a table. Need a difference between info and the rest.@macro tsubheading{text}@ifinfo@subsubheading \text\@end ifinfo@ifnotinfo@item @b{\text\}@end ifnotinfo@end macro@copyingThis manual is for Org-mode (version @value{VERSION}).Copyright @copyright{} 2004 Free Software Foundation@quotationPermission is granted to copy, distribute and/or modify this documentunder the terms of the GNU Free Documentation License, Version 1.1 orany later version published by the Free Software Foundation; with noInvariant Sections, with the Front-Cover texts being ``A GNU Manual,''and with the Back-Cover Texts as in (a) below. A copy of thelicense is included in the section entitled ``GNU Free DocumentationLicense.''(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modifythis GNU Manual, like GNU software. Copies published by the FreeSoftware Foundation raise funds for GNU development.''@end quotation@end copying@titlepage@title Org Mode Manual@subtitle Release @value{VERSION}@author by Carsten Dominik@c The following two commands start the copyright page.@page@vskip 0pt plus 1filll@insertcopying@end titlepage@c Output the table of contents at the beginning.@contents@ifnottex@node Top, Introduction, (dir), (dir)@top Org Mode Manual@insertcopying@end ifnottex@menu* Introduction:: Getting started* Document Structure:: A tree works like your brain* TODO items:: Every tree branch can be a TODO item* Tables:: Pure magic for quick formatting* Hyperlinks:: Notes in context* Timestamps:: Assign date and time to items* Timeline and Agenda:: Use time-stamped items to produce an agenda* Exporting:: Sharing and publishing of notes* 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@detailmenu --- The Detailed Node Listing ---Introduction* Summary:: Brief summary of what Org-mode does* Installation:: How to install Org-modeDocument Structure* Outlines:: Org-mode is based on outline-mode* Headlines:: How to typeset org-tree headlines* Visibility cycling:: Show ad hide, much simplified* Motion:: Jumping to other headlines* Structure editing:: Changing sequence and level of headlines* Sparse trees:: Matches embedded in contextTODO items* TODO basics:: Marking and displaying TODO entries* Priorities:: Some things are more important than others* TODO extensions:: Workflow and assignmentsExtended use of TODO keywords* Workflow states:: From TODO to DONE in steps* TODO types:: I do this, Fred the rest* Per file keywords:: Different files, different requirementsTables* Built-in table editor:: Simple tables* table.el:: Complex tables* orgtbl-mode:: The table editor as minor modeHyperlinks* Links:: URL-like links to the world* Remember:: Org-trees store quick notesTimestamps* Time stamps:: Assigning a time to a tree entry* Creating timestamps:: Commands which insert timestampsTimeline and Agenda* Timeline (single file):: Time-sorted view for single file* Agenda (multiple files):: Your weekly planner* Agenda commands:: Remote editing of org trees* Calendar/Diary integration:: Integrating Anniversaries and moreCalendar/Diary integration* Diary to agenda:: Agenda incorporates the diary* Agenda to diary:: Diary incorporates the agendaExporting* Export commands:: Commands which export and display* HTML formatting:: Interpretation of the buffer content* Export options:: How to influence exports* Comment lines:: Lines which will not be exportedMiscellaneous* Completion:: M-TAB knows what you need* Customization:: Adapting Org-mode to your taste* Tips and Tricks:: An author-imposed FAQ, sort of* Interaction:: Other Emacs packages* Acknowledgments:: These people provided feedback and more* Bugs:: Things which do not work perfectly@end detailmenu@end menu@node Introduction, Document Structure, Top, Top@chapter Introduction@cindex introduction@menu* Summary:: Brief summary of what Org-mode does* Installation:: How to install Org-mode@end menu@node Summary, Installation, Introduction, Introduction@section Summary@cindex summaryOrg-mode is a mode for keeping notes, maintaining ToDo lists, and doingproject planning with a fast and effective plain-text system.Org-mode develops organizational tasks around NOTES files that containinformation about projects as plain text. Org-mode is implemented ontop of outline-mode, which makes it possible to keep the content oflarge files well structured. Visibility cycling and structure editinghelp to work with the tree. Tables are easily created with a built-intable editor. Org-mode supports ToDo items, deadlines, time stamps,and scheduling. It dynamically compiles entries into an agenda.Plain text URL-like links connect to websites, emails, usenetmessages, BBDB entries, and any files related to the projects. Forprinting and sharing of notes, an Org-mode file can be exported as astructured ASCII file, or as HTML.Org-mode keeps simple things simple. Not every outline branch needsto be an action item, not every action item needs to have priority orscheduling information associated with it. Org-mode can be used ondifferent 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 to take structured notes}@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}@end exampleThe Org-mode table editor can be used integrated into any major modeby activating the minor Ortbl-mode.There is a website for Org-mode which provides links to the newestversion of Org-mode, as well as additional information, screen shotsand example files. This page is located at@uref{http://www.astro.uva.nl/~dominik/Tools/org/}.@page@node Installation, , Summary, Introduction@section Installation@cindex installation@cindex autoload@cindex global keybindings@cindex keybindings, globalThe instructions below assume that you have downloaded Org-mode fromthe web. If Org-mode is part of the Emacs distribution or an XEmacspackage, you only need to add to @file{.emacs} the last three Lisplines below - all the rest will be taken care of automatically.Byte-compile @file{org.el} and put it on your load path. If you'dlike to use the Info documentation, copy the file @file{org} into thedirectory containing info files and run the command @code{install-infoorg}.Then copy the following lines into @file{.emacs}. The last two linesdefine @emph{global} keys for the commands @command{org-store-link}and @command{org-agenda} - please choose suitable keys yourself.@lisp(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")(add-to-list 'auto-mode-alist '("\\.org$" . org-mode))(define-key global-map "\C-cl" 'org-store-link)(define-key global-map "\C-ca" 'org-agenda)@end lisp@cindex org-mode, turning on@noindentThis will put all files with extension @samp{.org} into Org-mode. Asan alternative, make the first line of a file look like this:@exampleMY PROJECTS -*- mode: org; -*-@end example@noindent which will select Org-mode for this buffer no matter whatthe file's name is.@node Document Structure, TODO items, Introduction, Top@chapter Document Structure@cindex document structure@cindex structure of documentOrg-mode is based on outline mode and provides flexible commands toedit the structure of the document.@menu* Outlines:: Org-mode is based on outline-mode* Headlines:: How to typeset org-tree headlines* Visibility cycling:: Show ad hide, much simplified* Motion:: Jumping to other headlines* Structure editing:: Changing sequence and level of headlines* Sparse trees:: Matches embedded in context@end menu@node Outlines, Headlines, Document Structure, Document Structure@section Outlines@cindex outlines@cindex outline-modeOrg-mode is implemented on top of outline-mode. Outlines allow toorganize a document in a hierarchical structure, which (at least forme) is the best representation of notes and thoughts. Overview overthis structure is achieved by folding (hiding) large parts of thedocument to show only the general document structure and the partscurrently being worked on. Org-mode greatly simplifies the use ofoutlines by compressing the entire show/hide functionality into asingle command @command{org-cycle}, which is bound to the @key{TAB}key.@node Headlines, Visibility cycling, Outlines, Document Structure@section Headlines@cindex headlines@cindex outline treeHeadlines define the structure of an outline tree. The Headlines inOrg-mode start with one or more stars, for example@example* Top level headline** Second level*** 3rd level some text*** 3rd level more text* Another top level headline@end example@node Visibility cycling, Motion, Headlines, Document Structure@section Visibility cycling@cindex visibility cycling@cindex trees, visibilityOutlines 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 changethe visibility in the buffer.@cindex subtree visibility states@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@example,-> FOLDED -> CHILDREN -> SUBTREE --.'-----------------------------------'@end exampleAt the beginning of the buffer (or when called with @kbd{C-u}), this doesthe same as the command @kbd{S-@key{TAB}} below.@cindex global visibility states@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@example,-> OVERVIEW -> CONTENTS -> SHOW ALL --.'--------------------------------------'@end exampleNote that inside tables, @kbd{S-@key{TAB}} jumps to the previous field.@cindex show all, command@kindex C-c C-a@item C-c C-aShow all.@end table@node Motion, Structure editing, Visibility cycling, Document Structure@section Motion@cindex motion, between headlines@cindex jumping, to headlinesThe following commands jump to other headlines in the buffer.@table @kbd@kindex C-c C-n@item C-c C-nNext heading.@kindex C-c C-p@item C-c C-pPrevious heading.@kindex C-c C-f@item C-c C-fNext heading same level.@kindex C-c C-b@item C-c C-bPrevious heading same level.@kindex C-c C-u@item C-c C-uBackward to higher level heading.@kindex C-c C-j@item C-c C-jJump to a different place without changing the current outlinevisibility. Shows the document structure in a temporary buffer, whereyou can use visibility cycling (@key{TAB}) to find your destination.After pressing @key{RET}, the cursor moves to the selected location inthe original buffer, and the headings hierarchy above it is madevisible.@end table@node Structure editing, Sparse trees, Motion, Document Structure@section Structure editing@cindex structure editing@cindex headline, promotion and demotion@cindex promotion, of subtrees@cindex demotion, of subtrees@cindex subtree, cut and paste@cindex pasting, subtrees@cindex cutting, subtrees@cindex copying, subtrees@table @kbd@kindex M-@key{RET}@item M-@key{RET}Insert new heading with same level as current@kindex M-@key{left}@item M-@key{left}Promote current heading by one level@kindex M-@key{right}@item M-@key{right}Demote current heading by one level@kindex M-S-@key{left}@item M-S-@key{left}Promote the current subtree by one level@kindex M-S-@key{right}@item M-S-@key{right}Demote the current subtree by one level@kindex M-S-@key{up}@item M-S-@key{up}Move subtree up (swap with previous subtree of same level)@kindex M-S-@key{down}@item M-S-@key{down}Move subtree down (swap with next subtree of same level)@kindex C-c C-h C-w@item C-c C-h C-wKill subtree, i.e. remove it from buffer but save in kill ring.@kindex C-c C-h M-w@item C-c C-h M-wCopy subtree to kill ring.@kindex C-c C-h C-y@item C-c C-h C-yYank subtree from kill ring. This does modify the level of subtree tomake sure the tree fits in nicely at the yank position. The yanklevel can also be specified with a prefix arg, or by yanking after aheadline marker like @samp{****}.@end table@cindex region, active@cindex active region@cindex transient-mark-modeWhen there is an active region (transient-mark-mode), promotion anddemotion work on all headlines in the region. To select a region ofheadlines, it is best to place both point and mark at the beginning of aline, mark at the beginning of the first headline, and point at the linejust after the last headline to change. Note that when the cursor isinside a table (@pxref{Tables}), the Meta-Cursor keys have differentfunctionality.@node Sparse trees, , Structure editing, Document Structure@section Sparse trees@cindex sparse trees@cindex trees, sparse@cindex folding, sparse trees@cindex occur, commandAn important feature of Org-mode is the ability to construct@emph{sparse trees} for selected information in an outline tree. Asparse tree means that the entire document is folded as much aspossible, but the selected information is made visible along with theheadline structure above it. Just try it out and you will seeimmediately how it works.Org-mode contains several commands creating such trees. The mostbasic one is @command{org-occur}:@table @kbd@kindex C-c /@item C-c /Occur. Prompts for a regexp and shows a sparse tree with all matches.If the match is in a headline, the headline is made visible. If thematch is in the body of an entry, headline and body are made visible.In order to provide minimal context, also the full hierarchy ofheadlines above the match is shown, as well as the headline followingthe match.@end tableOther commands are using this feature as well. For example @kbd{C-cC-v} creates a sparse TODO tree (@pxref{TODO basics}).@node TODO items, Tables, Document Structure, Top@chapter TODO items@cindex TODO itemsOrg-mode does not maintain TODO lists as a separate document. TODOitems are an integral part of the notes file, because TODO itemsusually come up while taking notes! With Org-mode, you simply markany entry in a tree as being a TODO item. In this way, theinformation is not duplicated, and the entire context from which theitem emerged is always present when you check.Of course, this technique causes TODO items to be scattered throughoutyour file. Org-mode provides methods to give you an overview over allthings you have to do.@menu* TODO basics:: Marking and displaying TODO entries* Priorities:: Some things are more important than others* TODO extensions:: Workflow and assignments@end menu@node TODO basics, Priorities, TODO items, TODO items@section Basic TODO functionalityAny headline can become a TODO item by starting it with the word TODO,for example@example*** TODO Write letter to Sam Fortune@end example@noindentThe most important commands to work with TODO entries are:@table @kbd@kindex C-c C-t@item C-c C-tRotate the TODO state of the current item between@example,-> (unmarked) -> TODO -> DONE --.'--------------------------------'@end example@kindex C-c C-v@cindex sparse tree, for TODO@item C-c C-vView TODO items in a @emph{sparse tree} (@pxref{Sparse trees}). Foldsthe entire buffer, but shows all TODO items and the headings hierarchyabove them. With prefix arg, show also the DONE entries.@end table@node Priorities, TODO extensions, TODO basics, TODO items@section Priorities@cindex prioritiesIf you use Org-mode extensively to organize your work, you may end upwith a number of TODO entries so large that you'd like to prioritizethem. You can do this by placing a @emph{priority cookie} into theheadline, like this@example*** TODO [#A] Write letter to Sam Fortune@end example@noindentWith its standard setup, Org-mode supports priorities @samp{A},@samp{B}, and @samp{C}. @samp{A} is the highest priority. An entrywithout a cookie is treated as priority @samp{B}. Priorities make adifference only in the multi-file agenda (@pxref{Agenda (multiple files)}).@table @kbd@kindex @kbd{C-c ,}@item @kbd{C-c ,}Set the priority of the current item. The command prompts for apriority character @samp{A}, @samp{B} or @samp{C}. When you press@key{SPC} instead, the priority cookie is removed from the headline.@kindex S-@key{up}@kindex S-@key{down}@item S-@key{up}@itemx S-@key{down}Increase/decrease priority of current item. Note that these keys arealso used to modify time stamps (@pxref{Creating timestamps}).@end table@node TODO extensions, , Priorities, TODO items@section Extended use of TODO keywords@cindex extended TODO keywordsThe default implementation of TODO entries is just two states: TODOand DONE. You can, however, use the TODO feature for morecomplicated things by configuring the variables@code{org-todo-keywords} and @code{org-todo-interpretation}. Usingspecial setup, you can even use TODO keywords in different ways indifferent org files.@menu* Workflow states:: From TODO to DONE in steps* TODO types:: I do this, Fred the rest* Per file keywords:: Different files, different requirements@end menu@node Workflow states, TODO types, TODO extensions, TODO extensions@subsection TODO keywords as workflow states@cindex TODO workflow@cindex workflow states as TODO keywordsYou can use TODO keywords to indicate different states in the processof working on an item, for example@lisp(setq org-todo-keywords '("TODO" "FEEDBACK" "VERIFY" "DONE") org-todo-interpretation 'sequence)@end lispWith this setup, the command @kbd{C-c C-t} will cycle an entry fromTODO to FEEDBACK, then to VERIFY, and finally too DONE. You may alsouse a prefix argument to quickly select a specific state. For example@kbd{C-3 C-c C-t} will change the state immediately to VERIFY.If you define many keywords, you can use in-buffer completion (see@ref{Completion}) to insert these words into the buffer.@node TODO types, Per file keywords, Workflow states, TODO extensions@subsection TODO keywords as types@cindex TODO types@cindex names as TODO keywords@cindex types as TODO keywordsThe second possibility is to use TODO keywords to indicate differenttypes of action items. For example, when you work with several peopleon a single project, you might want to assign action items topersons. @lisp(setq org-todo-keywords '("Fred" "Sara" "Lucy" "Mike" "DONE") org-todo-interpretation 'type)@end lispIn this case, different keywords do not indicate a sequence, butrather different levels. This changes the behavior of the command@kbd{C-c C-t} slightly. When used several times in succession, itwill still cycle through all names. But when when you return to theitem after some time and execute @kbd{C-c C-t} again, it will switchfrom each name directly to DONE. Use prefix arguments or completionto quickly select a specific name.@node Per file keywords, , TODO types, TODO extensions@subsection Setting up TODO keywords for individual files@cindex keyword options@cindex per file keywordsIt can be very useful to use different aspects of the TODO mechanismin different files. For this you need to add special lines to thefile which set the keywords and interpretation for that file only.For example, to set one of the two examples discussed above, youneed one of the following lines, starting in column zero anywhere inthe file:@example#+SEQ_TODO: TODO FEEDBACK VERIFY DONE#+TYP_TODO: Fred Sara Lucy Mike DONE@end example@cindex Completing option keywords@kindex M-@key{TAB}@noindent To make sure you are using the correct keyword, type@samp{#+} into the buffer and then use @kbd{M-@key{TAB}} completion.@cindex DONE, final TODO keywordRemember that the last keyword must always mean that theitem is DONE (you may use a different word, though). After changingthese lines, use @kbd{M-x normal-mode} to make the changes known toOrg-mode. Also note that in each file, only one of the two aspectsof TODO keywords can be used.If you want to use very many keywords, for example when working with alarge group of people, you may split the names over several lines:@example#+TYP_TODO: Fred Sara Lucy Mike#+TYP_TODO: Luis George Jules Jessica#+TYP_TODO: Kim Arnold Peter#+TYP_TODO: DONE@end example@node Tables, Hyperlinks, TODO items, Top@chapter Tables@cindex tablesFor taking notes, tables are an essential tool because they allowimmediate and clear structuring of data. Org-mode has a very fast andintuitive table editor built-in. More complex tables can be createdwith the Emacs table.el package.@menu* Built-in table editor:: Simple tables* table.el:: Complex tables* orgtbl-mode:: The table editor as minor mode@end menu@node Built-in table editor, table.el, Tables, Tables@section The built-in table editor@cindex table editor, builtinOrg-mode makes it easy to format tables in plain ASCII. Any line with@samp{|} as the first non-white character is considered part of atable. @samp{|} is also the column separator. A table might looklike this:@example| Name | Phone | Age ||-------+-------+-----|| Peter | 1234 | 17 || Anna | 4321 | 25 |@end exampleA table is re-aligned automatically each time you press @key{TAB} or@key{RET} inside the table. @key{TAB} also moves to the next field(@key{RET} to the next row) and creates new table rows at the end of thetable or before horizontal lines. The indentation of the table is setby the first line. Any line starting with @samp{|-} is considered as ahorizontal separator line and will be expanded on the next re-align tospan the whole table width. So, to create the above table, you wouldonly type@example|Name|Phone|Age|-@end example@noindent and then press @key{TAB} to align the table and start filling infields.@table @kbd@tsubheading{Creation and conversion}@kindex C-c C-c@item C-c C-cRecognize @file{table.el} table. Works when the cursor is in atable.el table@kindex C-c C-c@item C-c C-cConvert region to table. Works when the cursor is not in an existingtable, and when there is a region defined. If every line contains atleast one TAB character, the function assumes that the material is tabseparated. If not, lines are split at whitespace into fields. Youcan use a prefix argument to indicate how many consecutive spaces areat least required to indicate a field separator (default: just one).@item M-x org-table-createCreates an empty Org-mode table. However, it is much easier to juststart typing, like @kbd{|Name|Phone|Age @key{RET} |- @key{TAB}}@tsubheading{Re-aligning and field motion}@kindex C-c C-c@item C-c C-cRe-align the table without moving the cursor.@kindex @key{TAB}@item @key{TAB}Re-align the table, move to the next field. Creates a new row ifnecessary.@kindex S-@key{TAB}@item S-@key{TAB}Move to previous field.@kindex @key{RET}@item @key{RET}Re-align the table and move down to next row. Creates a new row ifnecessary. At the beginning or end of a line, @key{RET} still doesNEWLINE, so it can be used to split a table.@kindex S-@key{RET} @item S-@key{RET} Copy from first non-empty field above current field.@tsubheading{Column and row editing}@kindex M-@key{left}@kindex M-@key{right}@item M-@key{left}@itemx M-@key{right}Move the current column left/right@kindex M-S-@key{left}@item M-S-@key{left}Kill the current column.@kindex M-S-@key{right}@item M-S-@key{right}Insert a new column to the left of the cursor position.@kindex M-@key{up}@kindex M-@key{down}@item M-@key{up}@itemx M-@key{down}Move the current row up/down@kindex M-S-@key{up}@item M-S-@key{up}Kill the current row or horizontal line.@kindex M-S-@key{down}@item M-S-@key{down}Insert a new row above (with arg: below) the current row.@kindex C-c -@item C-c -Insert a horizontal line below current row. With prefix arg, line iscreated above the current line.@tsubheading{Regions}@kindex C-c C-h M-w@item C-c C-h M-wCopy an rectangular region from a table to a special clipboard. Pointand mark determine edge fields of the rectangle. The process ignoreshorizontal separator lines.@kindex C-c C-h C-w@item C-c C-h C-wCopy an rectangular region from a table to a special clipboard, andblank all fields in the rectangle.@kindex C-c C-h C-y@item C-c C-h C-yPaste a rectangluar region into a table.The upper right corner ends up in the current field. All involved fieldswill be overwritten. If the rectangle does not fit into the present table,the table is enlarged as needed. The process ignores horizontal separatorlines.@kindex C-c C-q@item C-c C-qWrap several fields in a column like a paragraph. If there is an activeregion, and both point and mark are in the same column, the text in thecolumn is wrapped to minimum width for the given number of lines. Aprefix ARG may be used to change the number of desired lines. If thereis no region, the current field is split at the cursor position and thetext fragment to the right of the cursor is prepended to the field oneline down. If there is no region, but you specify a prefix ARG, thecurrent field gets blank, and the content is appended to the fieldabove.@tsubheading{Calculations}@kindex C-c ?@item C-c ?Which table column is the cursor in? Displays number >0 in echoarea. @cindex region, active@cindex active region@cindex transient-mark-mode@kindex C-c +@item C-c +Sum the numbers in the current column, or in the rectangle defined bythe active region. The result is displayed in the echo area and canbe inserted with @kbd{C-y}.@cindex formula, in tables@cindex calculations, in tables@kindex C-c =@item C-c =Replace current field with the result of a formula. Requires theEmacs calc package. The formula can access the current field with@samp{$}, and the other fields in the current rowwith @samp{$1}, @samp{$2},... For details see the documentation of thecommand @command{org-table-eval-formula}.@tsubheading{Miscellaneous}@kindex C-c |@item C-c |Toggle the visibility of vertical lines in tables. The lines arestill there, only made invisible with a text property. Any @samp{|}added by hand will become invisible on the next align.Typographically it is good style to have no vertical lines in tables.@item M-x org-table-importImport a file as a table. The table should be TAB- or whitespaceseparated. Useful for example to import an Excel table or data from adatabase, because these programs generally can write TAB-separated textfiles. This command works by inserting the file into the buffer andthen converting the region to a table. Any prefix argument is passed onto the converter, which uses it to determine the separator.@item M-x org-table-exportExport the table as a TAB-separated file. Useful for data exchange withfor example Excel or database programs.@end tableIf you don't like the automatic table editor because it gets into yourway in lines which you would like to start with @samp{|}, you can turnit off with@lisp(setq org-enable-table-editor nil)@end lisp@noindent The only table command which then still works is@kbd{C-c C-c} to do a manual re-align.@node table.el, orgtbl-mode, Built-in table editor, Tables@section The @file{table.el} package@kindex C-c C-c@cindex table editor, table.el@cindex @file{table.el}More complex ASCII tables (with automatic line wrapping, column- androw-spanning, and alignment) can be created using the Emacs tablepackage by Takaaki Ota (@uref{http://sourceforge.net/projects/table}).When @key{TAB} or @kbd{C-c C-c} is pressed in such a table, Org-modewill call @command{table-recognize-table} and move the cursor into thetable. Inside a table, the keymap of Org-mode is inactive. In orderto execute org-related commands, leave the table.@table @kbd@kindex C-c #@item C-c #Insert a table.el table. If there is already a table at point, thiscommand converts it between the table.el format and the Org-modeformat. See the documentation string of the command@code{org-convert-table} for the restrictions under which this ispossible.@end table@node orgtbl-mode, , table.el, Tables@section The Orgtbl minor mode@cindex orgtbl-mode@cindex Minor mode for tablesIf you like the intuitive way the Org-mode table editor works, youmight want to use it also in other modes like text-mode or mail-mode.The minor mode Orgtbl-mode make this possible. You can always togglethe mode with @kbd{M-x orgtbl-mode}. To turn it on by default, forexample in mail mode, use@lisp(add-hook 'mail-mode-hook 'turn-on-orgtbl)@end lisp@node Hyperlinks, Timestamps, Tables, Top@chapter Hyperlinks@cindex hyperlinksJust like HMTL, Org-mode provides links to other files, usenetarticles, emails and much more.@menu* Links:: URL-like links to the world* Remember:: Org-trees store quick notes@end menu@node Links, Remember, Hyperlinks, Hyperlinks@section Links@cindex links@cindex GNUS links@cindex BBDB links@cindex VM links@cindex RMAIL links@cindex WANDERLUST links@cindex USENET links@cindex SHELL linksOrg-mode supports links to files, websites, usenet and email messages;and BBDB database entries. Links are just plain-text URL-like locators.The following list shows examples for each link type.@examplehttp://www.astro.uva.nl/~dominik @r{on the web}file:/home/dominik/images/jupiter.jpg @r{file, absolute path}file:papers/last.pdf @r{file, relative path}file:~/code/main.c:255 @r{file, with line number}news:comp.emacs @r{Usenet link}mailto:adent@@galaxy.net @r{Mail link}vm:folder @r{VM folder link}vm:folder#id @r{VM message link}vm://myself@@some.where.org/folder#id @r{VM on remote machine}wl:folder @r{WANDERLUST folder link}wl:folder#id @r{WANDERLUST message link}rmail:folder @r{RMAIL folder link}rmail:folder#id @r{RMAIL message link}gnus:group @r{GNUS group link}gnus:group#id @r{GNUS article link}bbdb:Richard Stallman @r{BBDB link}shell:ls *.org @r{A shell command}@end exampleA link may contain space characters and is terminated by the end ofthe line. Therefore, there can be only one link per line (but see thevariable @code{org-allow-space-in-links}).@cindex storing links@table @kbd@kindex C-c l@item C-c lStore a link to the current location. This is a @emph{global} commandwhich can be used in any buffer to create a link. The link will bestored for later insertion into an Org-mode buffer (see below). For VM,RMAIL, WANDERLUST, GNUS and BBDB buffers, the link will point to thecurrent article/entry. For W3 and W3M buffer, the link goes to thecurrent URL. For any other files, the link will just point to the file.The key binding @kbd{C-c l} is only a suggestion - see@ref{Installation}.@kindex C-c C-l@item C-c C-lInsert a link. This prompts for a link to be inserted into thebuffer. You can just type a link, using one of the link type prefixesmentioned in the examples above. Through completion, all links storedduring the current session can be accessed. When called with prefixarg, you can use file name completion to enter a file link. Note thatyou don't have to use this command to insert a link. Links inOrg-mode are plain text, and you can type or paste them straight intothe buffer.@cindex inserting links@kindex C-c C-o@item C-c C-oOpen link at point. This will launch a web browser for URLs (using@command{browse-url-at-point}), run vm/gnus/bbdb for the correspondinglinks, execute the command in a shell link, visit text files withEmacs and select a suitable application for non-text files.Classification of files is based on file extension only. See option@code{org-file-apps}. If there is no link at point, the currentsubtree will be searched for one. If you want to override the defaultapplication and visit the file with Emacs, use a @kbd{C-u} prefix.If the cursor is on a time stamp, compiles the agenda for that date.@strong{IMPORTANT}: Be careful not to use any dangerous commands in ashell link.@kindex mouse-2@item mouse-2On links, @kbd{mouse-2} will open the link just like @kbd{C-c C-o} would.@kindex mouse-3@item mouse-3Like @kbd{mouse-2}, but force file links to be opened with Emacs.@end table@node Remember, , Links, Hyperlinks@section Remember@cindex @file{remember.el}Another way to create org entries with links to other files is throughthe @emph{Remember} package by John Wiegley. @emph{Remember} lets youstore quick notes with little interruption of your work flow. See@uref{http://www.emacswiki.org/cgi-bin/wiki/RememberMode} for moreinformation. The notes produced by @emph{Remember} can be stored indifferent ways, and Org-mode files are a good target.Org-mode allows to file away notes either to a default file, ordirectly to the correct location in your Org-mode outline tree. Thefollowing customization will tell @emph{Remember} to use org files astarget, and to create annotations compatible with Org-mode links.@c FIXME: The autoload will not be necessary when Org-mode is part of Emacs@example(autoload 'org-remember-annotation "org")(autoload 'org-remember-handler "org")(setq org-directory "~/path/to/my/orgfiles/")(setq org-default-notes-file "~/.notes")(setq remember-annotation-functions '(org-remember-annotation))(setq remember-handler-functions '(org-remember-handler))@end exampleWhen you compose a note with remember, you have to press @kbd{C-c C-c}to exit remember-mode and to file away the note. The handler firstprompts for a target file - if you press @key{RET}, the value of@code{org-default-notes-file} is used. Then the command offers theheadings tree of the selected file. You can either immediately press@key{RET} to get the note appended to the file. Or you can usevertical cursor motion (@key{up} and @key{down}) and visibilitycycling (@key{TAB}) to find a better place. Pressing @key{RET} or@key{left} or @key{right} leads to the following result.@multitable @columnfractions 0.2 0.1 0.7@item @b{Cursor position} @tab @b{Key} @tab @b{Note gets inserted}@item buffer-start @tab @key{RET} @tab as level 2 heading at end of file@item on headline @tab @key{RET} @tab as sublevel of the heading at cursor@item @tab @key{left} @tab as same level, before current heading@item @tab @key{right} @tab as same level, after current heading@item not on headline @tab @key{RET} @tab at cursor position, level taken from context. Or use prefix arg to specify level manually.@end multitableSo the fastest way to store the note is to press @kbd{C-c C-c @key{RET}@key{RET}} to append it to the default file. But with little extraeffort, you can push it directly to the correct location.Before inserting the text into a tree, the function ensures that thetext has a headline, i.e. a first line that starts with a @samp{*}.If not, a headline is constructed from the current date and someadditional data. If the variable @code{org-adapt-indentation} isnon-nil, the entire text is also indented so that it starts in thesame column as the headline (after the asterixes).@node Timestamps, Timeline and Agenda, Hyperlinks, Top@chapter TimestampsItems can be labeled with timestamps to make them useful for projectplanning.@menu* Time stamps:: Assigning a time to a tree entry* Creating timestamps:: Commands which insert timestamps@end menu@node Time stamps, Creating timestamps, Timestamps, Timestamps@section Time stamps, deadlines and scheduling@cindex time stamps@cindex deadlines@cindex schedulingA time stamp is a specification of a date (possibly with time) in aspecial format, either @samp{<2003-09-16 Tue>} or @samp{<2003-09-16Tue 09:39>}. A time stamp can appear anywhere in the headline or bodyof an org-tree entry. Its presence allows to show entries on specificdates in the agenda (@pxref{Agenda (multiple files)}). We distinguish:@table @var@cindex timestamp@item TIMESTAMPA simple time stamp just assigns a date/time to an item. In thetimeline and agenda displays, the headline of the entry will be shownexactly on that date.@item TIMERANGE@cindex timerangeTwo time stamps connected by @samp{--} denote a time range. Theheadline will be shown on the first and last day of the range, and onany dates that are displayed and fall in the range. Here is anexample:@example** Meeting in Amsterdam <2004-08-23 Mon>--<2004-08-26 Thu>@end example@item DEADLINE@cindex deadlineIf a time stamp is preceded by the word @samp{DEADLINE:}, the task(most likely a TODO item) is supposed to be finished on that date, andit will be listed then. In addition, the compilation for the@emph{current day} will carry a warning about the approaching ormissed deadline, starting @code{org-deadline-warning-days} before thedue date, and continuing until the entry is marked DONE. An example:@example*** TODO write article about the Earth for the Guide The editor in charge is bbdb:Ford Prefect DEADLINE: <2004-02-29 Sun>@end example@item SCHEDULED@cindex scheduledIf a time stamp is preceded by the word @samp{SCHEDULED:}, it meansyou are planning to start working on that task on the given date. Theheadline will be listed under the given date. In addition, a reminderthat the scheduled date has passed will be present in the compilationfor the @emph{current day}, until the entry is marked DONE. I.e., thetask will automatically be forwarded.@end table@node Creating timestamps, , Time stamps, Timestamps@section Creating timestamps@cindex creating timestampsFor Org-mode to recognize time stamps, they need to be in the specificformat. All commands listed below produce time stamps in the correctformat.@table @kbd@kindex C-c .@item C-c .Prompt for a date and insert a corresponding time stamp. When thecursor is at a previously used time stamp, it is updated to NOW. Whenthis command is used twice in succession, a time range is inserted.@kindex C-u C-c .@item C-u C-c .Like @kbd{C-c .}, but use the alternative format which contains dateand time.@kindex C-c <@item C-c <Insert a time stamp corresponding to the cursor date in the Calendar.@kindex C-c >@item C-c >Access the Emacs calendar for the current date. If there is atimestamp in the current line, goto the corresponding dateinstead.@kindex C-c C-o@item C-c C-oAccess the agenda for the date given by the time stamp at point(@pxref{Agenda (multiple files)}).@kindex C-c C-d@item C-c C-dInsert @samp{DEADLINE} keyword along with a stamp.@kindex C-c C-w@cindex sparse tree, for deadlines@item C-c C-wCreate a sparse tree with all deadlines that are either past-due, orwhich will become due within @code{org-deadline-warning-days}.With @kbd{C-u} prefix, show all deadlines in the file. With a numericprefix, check that many days. For example, @kbd{C-1 C-c C-w} showsall deadlines due tomorrow.@kindex C-c C-s@item C-c C-sInsert @samp{SCHEDULED} keyword along with a stamp.@kindex S-@key{left}@kindex S-@key{right}@item S-@key{left}@itemx S-@key{right}Change date at cursor by one day.@kindex S-@key{up}@kindex S-@key{down}@item S-@key{up}@itemx S-@key{down}Change the item under the cursor in a timestamp. The cursor can be ona year, month, day, hour or minute. Note that if the cursor is not ata time stamp, these same keys modify the priority of an item(@pxref{Priorities}).@kindex C-c C-y@cindex evaluate time range@item C-c C-yEvaluate a time range by computing the difference between start andend. With prefix arg, insert result after the time range (in a table:into the following column).@end table@cindex date, reading in minibuffer@cindex time, reading in minibuffer@cindex calendar, for selecting dateWhen org prompts for a date/time, the function reading your input willreplace anything you choose not to specify with the current date andtime. For details, see the documentation string of@command{org-read-date}. Also, a calender will pop up to allowselecting a date. The calendar can be fully controlled from theminibuffer, and a date can be selected with the following commands:@table @kbd@kindex <@item <Scroll calendar backwards by one month.@kindex >@item >Scroll calendar forwards by one month.@kindex mouse-1@item mouse-1Select date by clicking on it.@kindex S-@key{right}@item S-@key{right}One day forward.@kindex S-@key{left}@item S-@key{left}One day back.@kindex S-@key{down}@item S-@key{down}One week forward.@kindex S-@key{up}@item S-@key{up}One week back.@kindex M-S-@key{right}@item M-S-@key{right}One month forward.@kindex M-S-@key{left}@item M-S-@key{left}One month back.@kindex @key{RET}@item @key{RET}Choose date in calendar (only if nothing typed into minibuffer).@end table@node Timeline and Agenda, Exporting, Timestamps, Top@chapter Timeline and Agenda@cindex agendaWe have already described three commands to filter importantinformation in an org file into a sparse tree (@pxref{Sparse trees}):@cindex sparse trees@itemize @bullet@itemThe TODO tree, (@kbd{C-c C-v}), see @ref{TODO items}.@itemThe occur tree @kbd{C-c /}, see @ref{TODO items}.@itemChecking upcoming deadlines with @kbd{C-c C-w}, see @ref{Creatingtimestamps}.@end itemize@noindentInstead of using the sparse trees, Org-mode can also collect andtime-sort the important items into a separate buffer, which we callthe @emph{timeline} of the org file. It can also collect informationfrom a @emph{list of files} and in this way provide an @emph{agenda}which covers all of your current projects, action items andappointments.@menu* Timeline (single file):: Time-sorted view for single file* Agenda (multiple files):: Your weekly planner* Agenda commands:: Remote editing of org trees* Calendar/Diary integration:: Integrating Anniversaries and more@end menu@node Timeline (single file), Agenda (multiple files), Timeline and Agenda, Timeline and Agenda@section Timeline for a single file@cindex single file summary@cindex agenda, for single file@cindex timeline, single file@cindex time-sorted viewThe timeline shows all time-stamped items in a single Org-mode file,in @emph{time-sorted view}. The main purpose of this command is togive an overview over events in a project.@table @kbd@kindex C-c C-r@item C-c C-rShow a time-sorted view of the org file, with all time-stamped itemsof today or later. When called with a @kbd{C-u} prefix, past dateswill be included as well. When called with two @kbd{C-u C-u}prefixes, all unfinished TODO entries (scheduled or not) are alsolisted under the current date.@end table@noindentThe timeline is shown in a temporary buffer @file{*Org Agenda*}. Thecommands available in the Agenda buffer are listed in @ref{Agendacommands}.@node Agenda (multiple files), Agenda commands, Timeline (single file), Timeline and Agenda@section Agenda from multiple files@cindex agenda, from multiple filesAn agenda can be compiled from one or more org files. The mainpurpose of this command is to act like a planner, in order to show youwhat tasks are up for the current week, similar to a paper agenda.The Org-mode files to be processed in order to generate the agenda arelisted in the variable @code{org-agenda-files}. You can customizethis variable, but the easiest way to maintain it is through thefollowing commands@cindex files, adding to agenda list@table @kbd@kindex C-c [@item C-c [Add current file to the list of agenda files@kindex C-c ]@item C-c ]Remove current file from the list of agenda files.@end table@noindentThe Org menu contains the list of all files and can be used to quicklyvisit any of them.The global command @command{org-agenda} compiles the agenda from alllisted files.@table @kbd@cindex org-agenda, command@kindex C-c a@item C-c aCompile an agenda for the current week from a list of org files. Theagenda shows the entries for each day. With a @kbd{C-u} prefix (orwhen the variable @code{org-agenda-include-all-todo} is @code{t}), allunfinished TODO items (also those without a date) are also listed atthe beginning of the buffer, before the first date.@*The key binding @kbd{C-c a} is only a suggestion - see@ref{Installation}.@end tableThe commands available in the Agenda buffer are listed in@ref{Agenda commands}.@subsection Categories@cindex categoryIn the agenda buffer, each entry is preceded by a @emph{category},which is derived from the file name. You can also set the category ofa file through file variables, for example by making the first line ofthe file look like this:@cindex file variables@examplePlanet Finder -*- mode: org; org-category: Cheops -*-@end example@noindentOr, like with TODO keywords (@pxref{Per file keywords}), you caninsert a special line anywhere in the file:@example#+CATEGORY: Cheops@end example@noindentThe display looks best if the category is no longer than 10 characters.@subsection Sorting of agenda items@cindex sorting, of agenda items@cindex priorities, of agenda itemsThe entries for each day are sorted. The default order is to firstcollect all items containing an explicit time-of-day specification.These entries will be shown at the beginning of the list, as a@emph{schedule} for the day. After that, items remain grouped incategories, in the sequence given by @code{org-agenda-files}. Withineach category, items are sorted by priority (@pxref{Priorities}).A time-of-day specification looks like @samp{12:45} or @samp{3pm} andmust appear in the headline. For example, a timestamp in a headlinethat contains not only a date but also a time will trigger thismechanism. Specifications of a time in diary entries are recognizedas well, so the schedule will be mixed from diary entries and Org-modefiles.The priority is a numerical quantity composed of the base priority(2000 for priority @samp{A}, 1000 for @samp{B}, and 0 for @samp{C}),plus additional increments for overdue scheduled or deadline items.Sorting can be customized using the variable@code{org-agenda-sorting-strategy}.@node Agenda commands, Calendar/Diary integration, Agenda (multiple files), Timeline and Agenda@section Commands in the agenda bufferEntries in the agenda buffer are linked back to the org file. You arenot allowed to edit the agenda buffer itself, but commands are providedto edit the org-files ``remotely'' from the agenda buffer. In thisway, all information is stored only once, and you don't risk that youragenda and note files diverge.Some commands can be executed with mouse clicks on agenda lines. Forthe other commands, the cursor needs to be in the desired line. Mostcommands are available for both timelines and the agenda. Theexceptions are marked.@table @kbd@tsubheading{View/GoTo org file}@kindex mouse-3@kindex @key{SPC}@item mouse-3@itemx @key{SPC} Display the original location of the item in another window.@kindex l@item lDisplay original location and recenter that window.@kindex mouse-2@kindex @key{TAB}@item mouse-2@itemx @key{TAB}Go to the original location of the item in another window.@kindex @key{RET}@itemx @key{RET}Go to the original location of the item and delete other windows.@kindex f@item fToggle follow mode. In follow mode, as you move the cursor throughthe agenda buffer, the other window always shows the correspondinglocation in the org file.@tsubheading{Change display}@kindex o@item oDelete other windows.@kindex w@item wToggle between weekly and daily view.@kindex d@item dToggle the inclusion of diary entries. See @ref{Calendar/Diary integration}.@kindex r@item rRecreate the agenda buffer, for example to reflect the changesafter modification of the time stamps of items with S-@key{left} andS-@key{right}.@kindex @key{right}@item @key{right}Display the following @code{org-agenda-ndays} days. For example, ifthe display covers a week, switch to the following week. With prefixarg, go forward that many times @code{org-agenda-ndays} days. Notavailable in timlines.@kindex @key{left}@item @key{left}Display the previous dates. Not available in timelines.@kindex .@item .Goto today.@tsubheading{Remote editing}@item 0-9Digit argument.@kindex t@item tChange the TODO state of the item, both in the agenda and in theoriginal org file.@kindex p@item pSet the priority for the current item. Org-mode prompts for thepriority character. If you reply with @key{SPC}, the priority cookieis removed from the entry.@kindex P@item pDisplay weighted priority of current item.@kindex +@item +Increase the priority of the current item. The priority is changed inthe original buffer, but the agenda is not resorted. Use the @kbd{r}key for this.@kindex -@item -Decrease the priority of the current item.@kindex S-@key{right}@item S-@key{right}Change the time stamp associated with the current line by one day intothe future. With prefix argument, change it by that many days. Forexample, @kbd{3 6 5 S-@key{right}} will change it by a year. Thestamp is changed in the original org file, but the change is notdirectly reflected in the agenda buffer. Use the @kbd{r} key to update the buffer.@kindex S-@key{left}@item S-@key{left}Change the time stamp associated with the current line by one dayinto the past.@kindex >@item >Change the time stamp associated with the current line to today.The key @kbd{>} has been chosen, because it is the same as @kbd{S-.}on my keyboard.@cindex diary entries, creating from agenda@kindex i@item iInsert a new entry into the diary. Prompts for the type of entry(day, weekly, monthly, yearly, anniversary, cyclic) and creates a newentry in the diary, just like @kbd{i d} etc. would do in the calendar.The date is taken from the cursor position.@tsubheading{Quit and Exit}@kindex q@item qQuit Agenda, remove the agenda buffer.@kindex x@cindex agenda files, removing buffers@item xExit agenda, remove the agenda buffer and all buffers loaded by Emacsfor the compilation of the agenda. Buffers created by the user tovisit org files will not be removed.@end table@node Calendar/Diary integration, , Agenda commands, Timeline and Agenda@section Calendar/Diary integration@cindex calendar integration@cindex diary integrationEmacs contains the calendar and diary by Edward M. Reingold. Thecalendar displays a three-month calendar with holidays from differentcountries and cultures. The diary allows to keep track ofanniversaries, lunar phases, sunrise/set, recurrent appointments(weekly, monthly) and more. In this way, it is quite complementary toOrg-mode. It can be very useful to combine output from Org-mode withthe diary.The interaction between Org-mode and diary works both ways: You canlist entries from the diary in the Org-mode agenda, or you can displayentries from the org agenda in the Emacs diary.@menu* Diary to agenda:: Agenda incorporates the diary* Agenda to diary:: Diary incorporates the agenda@end menu@node Diary to agenda, Agenda to diary, Calendar/Diary integration, Calendar/Diary integration@subsection Including the diary into the agenda@cindex diary to agendaIn order to include entries from the Emacs diary into Org-mode'sagenda, you only need to customize the variable@lisp(setq org-agenda-include-diary t)@end lisp@noindent@noindent After that, everything will happen automatically.@node Agenda to diary, , Diary to agenda, Calendar/Diary integration@subsection Including the agenda into the diaryIf you prefer to use the Emacs diary as your main instrument and ifyou wish to include the Org-mode agenda into it, the following stepsare necessary: Autoload the function @command{org-diary} as shownabove under @ref{Installation}. You also need to use @emph{fancydiary display} by setting in @file{.emacs}:@lisp(add-hook 'diary-display-hook 'fancy-diary-display)@end lispThen include the following line into your @file{~/diary} file, inorder to get the entries from all files listed in the variable@code{org-agenda-files}:@example&%%(org-diary)@end example@noindentYou may also select specific files with@example&%%(org-diary) ~/path/to/some/org-file.org&%%(org-diary) ~/path/to/another/org-file.org@end exampleIf you now launch the calendar and press @kbd{d} to display a diary,the headlines of entries containing a timestamp, date range, schedule,or deadline referring to the selected date will be listed. Just likein Org-mode's agenda view, the diary for @emph{today} containsadditional entries for overdue deadlines and scheduled items. Seealso the documentation of the @command{org-diary} function.@node Exporting, Miscellaneous, Timeline and Agenda, Top@chapter Exporting@cindex exporting@cindex ASCII file@cindex HTML@cindex headline levels, for exportingFor printing and sharing of notes, an Org-mode document can beexported as an ASCII file, or as HTML. In the exported version, thefirst 3 outline levels will become headlines, defining a generaldocument structure. Additional levels will be exported as itemizelists. If you want that transition to occur at a different level,specify it with a prefix argument. For example,@example@kbd{M-1 M-x org-export-as-html}@end example@noindentcreates only top level headlines and does the rest as items.@menu* Export commands:: Commands which export and display* HTML formatting:: Interpretation of the buffer content* Export options:: How to influence exports* Comment lines:: Lines which will not be exported@end menu@node Export commands, HTML formatting, Exporting, Exporting@section Export commands@cindex region, active@cindex active region@cindex transient-mark-mode@table @kbd@kindex C-c C-x a @item C-c C-x aExport as ASCII file. If there is an active region, only the regionwill be exported. For an org file @file{myfile.org}, the ASCII filewill be @file{myfile.txt}. The file will be overwritten withoutwarning.@kindex C-c C-x h @item C-c C-x hExport as HTML file @file{myfile.html}.@kindex C-c C-x C-h @item C-c C-x C-hExport as HTML file and open it with a browser.@kindex C-c C-x t@item C-c C-x tInsert template with export options, see below.@kindex C-c :@item C-c :Toggle fixed-width for line or region, see below.@end table@node HTML formatting, Export options, Export commands, Exporting@section HTML formattingNot all text is transferred literally to the exported HTML file. Theexporter implements the following interpretation:@itemize @bullet@cindex underlined text@cindex bold text@cindex italic text@itemYou can make words @b{*bold*}, @i{/italic/}, and _underlined_@cindex @TeX{} interpretation@itemSimple @TeX{}-like math constructs are interpreted:@itemize @minus@item@samp{10^22} and @samp{J_n} are super- and subscripts. You can quote@samp{^} and @samp{_} with a backslash: @samp{\_} and @samp{\^}@item@samp{\alpha} indicates a Greek letter, @samp{\to} an arrow. You canuse completion for these macros, just type @samp{\} and maybe a fewletters, and press @kbd{M-@key{TAB}} to see possible completions.@end itemize@cindex tables, export to HTML@itemTables are transformed into HTML tables.@cindex fixed width@itemLines starting with @samp{:} are typeset in a fixed-width font, toallow quoting of computer code etc. @cindex HTML tags@itemIf you want to include HTML tags which should be interpreted as such,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.@end itemizeIf these conversions conflict with your habits of typing ASCII text,they can all be turned off with corresponding variables.@node Export options, Comment lines, HTML formatting, Exporting@section Export options@cindex options, for exportThe exporter recognizes special lines in the buffer which provideadditional information. These lines may be put anywhere in the file.The whole set of lines can be inserted into the buffer with @kbd{C-cC-x t}. For individual lines, a good way to make sure the keyword iscorrect it to type @samp{#+} and then use @kbd{M-@key{TAB}} completion(@pxref{Completion}). @example#+TITLE: the title to be shown (default is the buffer name)#+AUTHOR: the author (default taken from @code{user-full-name})#+EMAIL: his/her email address (default from @code{user-mail-address})#+LANGUAGE: language for HTML, e.g. @samp{en} (@code{org-export-default-language})#+TEXT: Some descriptive text to be inserted at the beginning.#+TEXT: Several lines may be given.#+OPTIONS: H:2 num:t toc:t \n:nil @:t ::t |:t ^:t *:nil TeX:t@end example@noindentThe OPTIONS line is a compact form to specify export settings. Hereyou can@cindex headline levels@cindex section-numbers@cindex table of contents@cindex linebreak-preservation@cindex quoted html tags@cindex fixed-width sections@cindex tables@cindex @TeX{}-like syntax for sub- and superscripts@cindex emphasized text@cindex @TeX{} macros@exampleH: @r{set the number of headline levels for export}num: @r{turn on/off section-numbers}toc: @r{turn on/off table of contents}\n: @r{turn on/off linebreak-preservation}@@: @r{turn on/off quoted html tags}:: @r{turn on/off fixed-width sections}|: @r{turn on/off tables}^: @r{turn on/off @TeX{}-like syntax for sub- and superscripts.}*: @r{turn on/off emphasized text (bold, italic, underlined)}TeX: @r{turn on/off @TeX{} macros}@end example@node Comment lines, , Export options, Exporting@section Comment lines@cindex comment lines@cindex exporting, notLines starting with @samp{#} in column zero are treated as commentsand will never be exported. Also entire subtrees starting with theword @samp{COMMENT} will never be exported. Finally, any text beforethe first headline will not be exported either.@table @kbd@kindex C-c ;@item C-c ;Toggle the COMMENT keyword at the beginning of an entry.@end table@node Miscellaneous, Index, Exporting, Top@chapter Miscellaneous@menu* Completion:: M-TAB knows what you need* Customization:: Adapting Org-mode to your taste* Tips and Tricks:: An author-imposed FAQ, sort of* Interaction:: Other Emacs packages* Acknowledgments:: These people provided feedback and more* Bugs:: Things which do not work perfectly@end menu@node Completion, Customization, Miscellaneous, Miscellaneous@section Completion@cindex complete @TeX{} symbols@cindex complete TODO keywords@cindex complete dictionary words@cindex complete option keywordsOrg-mode supports in-buffer completion. This type of completion doesnot make use of the minibuffer. You simply type a few letters intothe buffer and use the key to complete text right there.@table @kbd@kindex M-@key{TAB}@item M-@key{TAB}Complete word at point@itemize @bullet@itemAt the beginning of a headline, complete TODO keywords.@itemAfter @samp{\}, complete @TeX{} symbols supported by the exporter.@itemAfter @samp{#+}, complete the special keywords like @samp{TYP_TODO} or@samp{OPTIONS} which set file-specific options for Org-mode. When theoption keyword is already complete, pressing @kbd{M-@key{TAB}} againwill insert example settings for this keyword.@itemElsewhere, complete dictionary words using ispell.@end itemize@end table@node Customization, Tips and Tricks, Completion, Miscellaneous@section Customization@cindex customization@cindex options, for customization@cindex variables, for customizationThere is a large number of variables which can be used to customizeOrg-mode. For the sake of compactness of the manual, we are notdescribing the variables here. For an overview of customizationvariables, use @kbd{M-x org-customize}. Or select @code{Browse OrgGroup} from the @code{Org->Customization} menu.@node Tips and Tricks, Interaction, Customization, Miscellaneous@section Tips and Tricks@itemize @bullet@cindex README files@itemI find Org-mode very useful for the many @file{README} files I havescattered through my directories. So I turn on @file{org-mode} forall @file{README} files with@example(add-to-list 'auto-mode-alist '("README$" . org-mode))@end example@ignore@cindex files, adding automatically@itemIf you would like to add all org files you ever create to the list ofagenda files@footnote{Think twice. Do you @emph{really} want this?},you could do so with@lisp(add-hook 'org-mode-hook 'org-add-file)@end lispIf you would like to add only a selection, for example everythingexcept the @file{README} files, this could be achieved in thefollowing way:@lisp(add-hook 'org-mode-hook (lambda () (or (string-match "README\\'" (buffer-file-name)) (org-add-file))))@end lisp@end ignore@cindex @code{make-indirect-buffer}@cindex indirect buffers@itemIt can be useful to have two different windows showing the sameOrg-mode file. However, a problem here is that changes to thevisibility in one window immediately affect the other window. OnEmacs (not on XEmacs because it uses the old outline-mode) a way outis the use of @emph{indirect buffers}, which visit the same file, buthave separate settings, also for outline visibility. See thedocumentation on the command @code{make-indirect-buffer}.@cindex URL, paste into buffer@itemPaste URLs into Org-mode whenever this seems useful. For example, ifyou are writing notes about a paper which is available on the web, putthe corresponding URL there and a direct look at the paper is only amouse click away. If you have a local copy of the paper, use afile:path link.@cindex headline levels, for export@itemIf you plan to use ASCII or HTML export, make sure things you want tobe exported as item lists are level 4 at least, even if that does meanthere is a level jump. For example@example* Todays top priorities**** TODO write a letter to xyz**** TODO Finish the paper**** Pick up kids at the school@end exampleAlternatively, if you need a specific value for the heading/itemtransition in a particular file, use the @samp{+OPTIONS} line toconfigure the @samp{H} switch.@example+OPTIONS: H:2; ...@end example@cindex exporting a subtree@itemIf you want to export a subtree, mark the subtree as region and thenexport. Marking can be done with @kbd{C-c @@ C-x C-x}, for example.@cindex table, empty template@itemTo insert an empty table template, just type @samp{|-} and use@key{TAB}.@itemIn a table, to add a new column at the end, just type some textanywhere after the final @samp{|}. Upon the next re-align, a newcolumn will be created.@itemIn tables, @key{TAB} creates new rows before horizontal separator lines. Ifthe cursor is at @samp{Age} in the following table,@example| Name | Phone | Age ||-------+-------+-----|| | | |@end examplethe next @key{TAB} would create a second header line. If you wantinstead to go to the first empty field below the horizontal line,press @key{down} (to get on the separator line) and then @key{TAB}.@cindex indentation, of tables@itemTo change the indentation of a table, just change the first line andrealign with @key{TAB}.@end itemize@node Interaction, Acknowledgments, Tips and Tricks, Miscellaneous@section Interaction with other packages@cindex packages, interaction with other@cindex @file{planner.el}@cindex @file{remember.el}@cindex @file{table.el}@file{Org.el} can cooperate with the following packages:@table @asis@cindex @file{remember.el}@item @file{remember.el} by John WiegleyOrg mode cooperates with remember, see @ref{Remember}.@cindex @file{plannner.el}@item @file{planner.el} by John WiegleyPlanner is another tool to plan work and keep track of tasks. Planneruses a multi-file approach with project pages and day pages. Is basedon Emacs-Wiki. It can be useful to display the agenda entriesresulting from org files in day-pages of the planner. This can bedone through the diary of the calendar: Integrate org files into thediary as described above, and then turn on the diary support ofplanner.@cindex @file{table.el}@item @file{table.el} by Takaaki OtaOrg mode cooperates with table.el, see @ref{table.el}.@end table@c EmacsWiki@c organizer-mode@c todo-mode@c records mode@page @c FIXME@node Acknowledgments, Bugs, Interaction, Miscellaneous@section Acknowledgments@cindex acknowledgmentsOrg-mode was written by Carsten Dominik, who still maintains it at theOrg-mode homepage@uref{http://www.astro.uva.nl/~dominik/Tools/org/}. The followingpeople have helped the development along with ideas, suggestions andpatches. @itemize @bullet@itemMatthias Rempe (Oelde) provided ideas and suggestions, a patchintroducing Windows NT/2000 support, and quality control.@itemKevin Rogers contributed code to access VM files on remote hosts.@itemJuergen Vollmer contributed code generating the table of contentsin HTML output, and other export improvements.@itemChristian Egli converted the documentation into TeXInfo format. Healso showed me his plans for a multifile summary for Org-mode. Some ofhis ideas have found their way into the agenda.@item Philip Rooke created the Org-mode reference card and did somebeta-testing.@itemLinking to VM/BBDB/GNUS was inspired by Tom Shannon's@file{organizer-mode.el}.@itemScheduling TODO items was inspired by John Wiegley's @file{planner.el}.@itemSacha Chua, the current maintainer of Planner suggested to take somelinking code from Planner, which I did (for RMAIL and Wanderlust).@itemOliver Oppitz sent several useful suggestions.@itemCarsten Wimmer suggested some changes and helped fix a bug in linkingto GNUS.@end itemize@node Bugs, , Acknowledgments, Miscellaneous@section Bugs@cindex bugsHere is a list of things which should work differently, but which Ihave found too hard to fix.@itemize @bullet@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 openthe file), it does so silently. No error message is displayed.@item Under XEmacs, if Org-mode entries are included into the diary, it isnot possible to jump back from the diary to the org file. Apparently,the text properties are lost when the fancy-diary-display is used.However, from Org-mode's agenda (created with @kbd{C-c C-r} or@kbd{M-x org-agenda}), things do work correctly.@item Linux should also have a default viewer application, using mailcap.Maybe we can use GNUS or VM mime code? Or dired's guessing commands?Any hints (or even patches) are appreciated.@item When you write @samp{x = a /b/ c}, b will be exported in italics.@item The exporters work well, but could be made more efficient.@end itemize@node Index, Key Index, Miscellaneous, Top@chapter Index@printindex cp@node Key Index, , Index, Top@chapter Key Index@printindex ky@bye@ignore arch-tag: 7893d1fe-cc57-4d13-b5e5-f494a1bcc7ac@end ignore