[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to emacs/doc/misc/org.texi,v
|
From: |
Carsten Dominik |
|
Subject: |
[Emacs-diffs] Changes to emacs/doc/misc/org.texi,v |
|
Date: |
Tue, 17 Jun 2008 15:22:02 +0000 |
CVSROOT: /sources/emacs
Module name: emacs
Changes by: Carsten Dominik <cdominik> 08/06/17 15:22:01
Index: doc/misc/org.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/misc/org.texi,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -b -r1.10 -r1.11
--- doc/misc/org.texi 15 Jun 2008 02:24:02 -0000 1.10
+++ doc/misc/org.texi 17 Jun 2008 15:21:55 -0000 1.11
@@ -3,8 +3,8 @@
@setfilename ../../info/org
@settitle The Org Manual
address@hidden VERSION 6.02b
address@hidden DATE April 2008
address@hidden VERSION 6.05a
address@hidden DATE June 2008
@dircategory Emacs
@direntry
@@ -43,8 +43,8 @@
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
and with the Back-Cover Texts as in (a) below. A copy of the
-license is included in the section entitled ``GNU Free Documentation
-License'' in the Emacs manual.
+ license is included in the section entitled ``GNU Free Documentation
+-License.''
(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
modify this GNU manual. Buying copies from the FSF supports it in
@@ -94,7 +94,8 @@
* Exporting:: Sharing and publishing of notes
* Publishing:: Create a web site of linked Org files
* Miscellaneous:: All the rest which did not fit elsewhere
-* Extensions and Hacking:: It is possible to write add-on code
+* Extensions::
+* Hacking::
* History and Acknowledgments:: How Org came into being
* Main Index:: An index of Org's concepts and features
* Key Index:: Key bindings and where they are described
@@ -279,16 +280,35 @@
Exporting
+* Markup rules:: Which structures are recognized?
+* Export options:: Per-file export settings
+* The export dispatcher:: How to access exporter commands
* ASCII export:: Exporting to plain ASCII
* HTML export:: Exporting to HTML
* LaTeX export:: Exporting to LaTeX
* XOXO export:: Exporting to XOXO
* iCalendar export:: Exporting in iCalendar format
-* Text interpretation:: How the exporter looks at the file
+
+Markup rules
+
+* Document title:: How the document title is determined
+* Headings and sections:: The main structure of the exported document
+* Table of contents:: If, where, how to create a table of contents
+* Initial text:: Text before the first headline
+* Lists:: Plain lists are exported
+* Paragraphs:: What determines beginning and ending
+* Literal examples:: Source code and other examples
+* Include files:: Include the contents of a file during export
+* Tables exported:: Tables are exported richly
+* Footnotes:: Numbers like [1]
+* Emphasis and monospace:: To bold or not to bold
+* TeX macros and LaTeX fragments:: Create special, rich export.
+* Horizontal rules:: A line across the page
+* Comment lines:: Some lines will not be exported
HTML export
-* HTML Export commands:: How to invoke LaTeX export
+* HTML Export commands:: How to invoke HTML export
* Quoting HTML tags:: Using direct HTML in Org mode
* Links:: Transformation of links for HTML
* Images:: How to include images
@@ -301,15 +321,6 @@
* Quoting LaTeX code:: Incorporating literal LaTeX code
* Sectioning structure:: Changing sectioning in LaTeX output
-Text interpretation by the exporter
-
-* Comment lines:: Some lines will not be exported
-* Initial text:: Text before the first headline
-* Footnotes:: Numbers like [1]
-* Quoted examples:: Inserting quoted chunks of text
-* Enhancing text:: Subscripts, symbols and more
-* Export options:: How to influence the export settings
-
Publishing
* Configuration:: Defining projects
@@ -347,14 +358,19 @@
* Cooperation:: Packages Org cooperates with
* Conflicts:: Packages that lead to conflicts
-Extensions, Hooks and Hacking
+Extensions
+
+* Extensions in the contrib directory:: These come with the Org distro
+* Other extensions:: These you have to find on the web.
+
+Hacking
-* Extensions:: Existing 3rd-party extensions
* Adding hyperlink types:: New custom link types
* Tables in arbitrary syntax:: Orgtbl for LaTeX and other programs
* Dynamic blocks:: Automatically filled blocks
* Special agenda views:: Customized views
* Using the property API:: Writing programs that use entry properties
+* Using the mapping API:: Mapping over all or selected entries
Tables and lists in arbitrary syntax
@@ -561,9 +577,10 @@
@cindex maintainer
@cindex author
-If you find problems with Org, or if you have questions, remarks,
-or ideas about it, please contact the maintainer @value{MAINTAINER} at
address@hidden
+If you find problems with Org, or if you have questions, remarks, or ideas
+about it, please mail to the Org mailing list @code{emacs-orgmode@@gnu.org}.
+If you are not a member of the mailing list, your mail will be reviewed by a
+moderator and then passed through to the list.
For bug reports, please provide as much information as possible,
including the version information of Emacs (@kbd{C-h v emacs-version
@@ -792,6 +809,19 @@
#+STARTUP: showall
@end example
address@hidden
+Forthermore, any entries with a @samp{VISIBILITY} property (@pxref{Properties
+and Columns}) will get their visibility adapted accordingly. Allowed values
+for this property are @code{folded}, @code{children}, @code{content}, and
address@hidden
address@hidden @kbd
address@hidden C-u C-u @key{TAB}
address@hidden C-u C-u @key{TAB}
+Switch back to the startup visibility of the buffer, i.e. whatever is
+requested by startup options and @samp{VISIBILITY} properties in individual
+entries.
address@hidden table
+
@node Motion, Structure editing, Visibility cycling, Document Structure
@section Motion
@cindex motion, between headlines
@@ -915,6 +945,12 @@
also supply your own function to extract the sorting key. With a @kbd{C-u}
prefix, sorting will be case-sensitive. With two @kbd{C-u C-u} prefixes,
duplicate entries will also be removed.
address@hidden C-x n s
address@hidden C-x n s
+Narrow buffer to current subtree.
address@hidden C-x n w
address@hidden C-x n w
+Widen buffer to remove a narrowing.
@kindex C-c *
@item C-c *
Turn a normal line or plain list item into a headline (so that it
@@ -1064,14 +1100,14 @@
@cindex folding, sparse trees
@cindex occur, command
-An important feature of Org mode is the ability to construct
address@hidden trees} for selected information in an outline tree, so that
-the entire document is folded as much as possible, but the selected
-information is made visible along with the headline structure above
address@hidden also the variables @code{org-show-hierarchy-above},
address@hidden, and @code{org-show-siblings} for
-detailed control on how much context is shown around each match.}. Just
-try it out and you will see immediately how it works.
+An important feature of Org mode is the ability to construct @emph{sparse
+trees} for selected information in an outline tree, so that the entire
+document is folded as much as possible, but the selected information is made
+visible along with the headline structure above address@hidden also the
+variables @code{org-show-hierarchy-above}, @code{org-show-following-heading},
address@hidden, and @code{org-show-entry-below} for detailed
+control on how much context is shown around each match.}. Just try it out
+and you will see immediately how it works.
Org mode contains several commands creating such trees, all these
commands can be accessed through a dispatcher:
@@ -1082,15 +1118,16 @@
This prompts for an extra key to select a sparse-tree creating command.
@kindex C-c / r
@item C-c / r
-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 the
-match is in the body of an entry, headline and body are made visible.
-In order to provide minimal context, also the full hierarchy of
-headlines above the match is shown, as well as the headline following
-the match. Each match is also highlighted; the highlights disappear
-when the buffer is changed by an editing command, or by pressing
address@hidden C-c}. When called with a @kbd{C-u} prefix argument, previous
-highlights are kept, so several calls to this command can be stacked.
+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 the match is in
+the body of an entry, headline and body are made visible. In order to
+provide minimal context, also the full hierarchy of headlines above the match
+is shown, as well as the headline following the match. Each match is also
+highlighted; the highlights disappear when the buffer is changed by an
+editing address@hidden on the option
address@hidden, or by pressing @kbd{C-c C-c}.
+When called with a @kbd{C-u} prefix argument, previous highlights are kept,
+so several calls to this command can be stacked.
@end table
@noindent
@@ -1133,24 +1170,34 @@
checkboxes (@pxref{Checkboxes}). Org supports editing such lists,
and the HTML exporter (@pxref{Exporting}) parses and formats them.
-Org knows ordered and unordered lists. Unordered list items start
-with @samp{-}, @samp{+}, or @address@hidden using @samp{*} as a
-bullet, lines must be indented or they will be seen as top-level
-headlines. Also, when you are hiding leading stars to get a clean
-outline view, plain list items starting with a star are visually
-indistinguishable from true headlines. In short: even though @samp{*}
-is supported, it may be better to not use it for plain list items.} as
-bullets. Ordered list items start with a numeral followed by either a
-period or a right parenthesis, such as @samp{1.} or @samp{1)}. Items
-belonging to the same list must have the same indentation on the first
-line. In particular, if an ordered list reaches number @samp{10.}, then
-the 2--digit numbers must be written left-aligned with the other numbers
-in the list. Indentation also determines the end of a list item. It
-ends before the next line that is indented like the bullet/number, or
-less. Empty lines are part of the previous item, so you can have
-several paragraphs in one item. If you would like an empty line to
-terminate all currently open plain lists, configure the variable
address@hidden Here is an example:
+Org knows ordered lists, unordered lists, and description lists.
address@hidden @bullet
address@hidden
address@hidden list items start with @samp{-}, @samp{+}, or
address@hidden@footnote{When using @samp{*} as a bullet, lines must be indented
or
+they will be seen as top-level headlines. Also, when you are hiding leading
+stars to get a clean outline view, plain list items starting with a star are
+visually indistinguishable from true headlines. In short: even though
address@hidden is supported, it may be better to not use it for plain list
items.}
+as bullets.
address@hidden
address@hidden list items start with a numeral followed by either a period or
+a right parenthesis, such as @samp{1.} or @samp{1)}.
address@hidden
address@hidden list items are like unordered list items, but contain the
+separator @samp{ :: } to separate the description @emph{term} from the
+desciption.
address@hidden itemize
+
+Items belonging to the same list must have the same indentation on the first
+line. In particular, if an ordered list reaches number @samp{10.}, then the
+2--digit numbers must be written left-aligned with the other numbers in the
+list. Indentation also determines the end of a list item. It ends before
+the next line that is indented like the bullet/number, or less. Empty lines
+are part of the previous item, so you can have several paragraphs in one
+item. If you would like an empty line to terminate all currently open plain
+lists, configure the variable @code{org-empty-line-terminates-plain-lists}.
+Here is an example:
@example
@group
@@ -1164,6 +1211,10 @@
- on DVD only
He makes a really funny face when it happens.
But in the end, not individual scenes matter but the film as a whole.
+ Important actors in this film are:
+ - @b{Elijah Wood} :: He plays the Frodo
+ - @b{Sean Austin} :: He plays the Sam, Frodos friend. I still remember
+ him very well from his role as Mikey Walsh a in the Goonies.
@end group
@end example
@@ -1171,7 +1222,8 @@
deal with them address@hidden only changes the filling
settings for Emacs. For XEmacs, you should use Kyle E. Jones'
@file{filladapt.el}. To turn this on, put into @file{.emacs}:
address@hidden(require 'filladapt)}}.
address@hidden(require 'filladapt)}}, and by exporting them properly
+(@pxref{Exporting}).
The following commands act on items when the cursor is in the first line
of an item (the line with the bullet or number).
@@ -1265,7 +1317,8 @@
hide and show the entry, but keep the drawer collapsed to a single line.
In order to look inside the drawer, you need to move the cursor to the
drawer line and press @key{TAB} there. Org mode uses a drawer for
-storing properties (@pxref{Properties and Columns}).
+storing properties (@pxref{Properties and Columns}), and another one for
+storing clock times (@pxref{Clocking work time}).
@node Orgstruct mode, , Drawers, Document Structure
@section The Orgstruct minor mode
@@ -1520,7 +1573,10 @@
used to export the file can be configured in the variable
@code{org-table-export-default-format}. You may also use properties
@code{TABLE_EXPORT_FILE} and @code{TABLE_EXPORT_FORMAT} to specify the file
-name and the format for table export in a subtree.
+name and the format for table export in a subtree. Org supports quite
+general formats for exported tables. The exporter format is the same as the
+format used by Orgtbl radio tables, see @ref{Translator functions} for a
+detailed description.
@end table
If you don't like the automatic table editor because it gets in your
@@ -2656,8 +2712,6 @@
an implementation example. Search for @samp{BibTeX links} in the source
file.
-
-
@node TODO Items, Tags, Hyperlinks, Top
@chapter TODO Items
@cindex TODO items
@@ -3136,12 +3190,37 @@
@cindex tasks, breaking down
It is often advisable to break down large tasks into smaller, manageable
-subtasks. You can do this by creating an outline tree below a TODO
-item, with detailed subtasks on the address@hidden keep subtasks out
-of the global TODO list, see the
address@hidden Another possibility is the use
-of checkboxes to identify (a hierarchy of) a large number of subtasks
-(@pxref{Checkboxes}).
+subtasks. You can do this by creating an outline tree below a TODO item,
+with detailed subtasks on the address@hidden keep subtasks out of the
+global TODO list, see the @code{org-agenda-todo-list-sublevels}.}. To keep
+the overview over the fraction of subtasks that are already completed, insert
+either @samp{[/]} or @samp{[%]} anywhere in the headline. These cookies will
+be updates each time the todo status of a child changes. For example:
+
address@hidden
+* Organize Party [33%]
+** TODO Call people [1/2]
+*** TODO Peter
+*** DONE Sarah
+** TODO Buy food
+** DONE Talk to neighbor
address@hidden example
+
+If you would like a TODO entry to automatically change to DONE when all
+chilrden are done, you can use the following setup:
+
address@hidden
+(defun org-summary-todo (n-done n-not-done)
+ "Switch entry to DONE when all subentries are done, to TODO otherwise."
+ (let (org-log-done org-log-states) ; turn off logging
+ (org-todo (if (= n-not-done 0) "DONE" "TODO"))))
+
+(add-hook 'org-after-todo-statistics-hook 'org-summary-todo)
address@hidden example
+
+
+Another possibility is the use of checkboxes to identify (a hierarchy of) a
+large number of subtasks (@pxref{Checkboxes}).
@node Checkboxes, , Breaking down tasks, TODO Items
@@ -3268,14 +3347,24 @@
@noindent
the final heading will have the tags @samp{:work:}, @samp{:boss:},
@samp{:notes:}, and @samp{:action:} even though the final heading is not
-explicitly marked with those tags. When executing tag searches and
-Org mode finds that a certain headline matches the search criterion, it
-will not check any sublevel headline, assuming that these also match and
-that the list of matches could become very long because of that. If you
-do want the sublevels be tested and listed as well, you may set the
-variable @code{org-tags-match-list-sublevels}. To limit tag inheritance
-to specific tags, or to turn it off entirely, use the variable
address@hidden
+explicitly marked with those tags. You can also set tags that all entries in
+a file should inherit as if these tags would be defined in a hypothetical
+level zero that surounds the entire file.
+
address@hidden
+#+FILETAGS: :Peter:Boss:Secret:
address@hidden example
+
address@hidden
+To limit tag inheritance to specific tags, or to turn it off entirely, use
+the variable @code{org-use-tag-inheritance}.
+
+When a headline matches during a tags search while tag inheritance is turned
+on, all the sublevels in the same tree will match as address@hidden is
+only true if the the search does not involve more complex tests including
+properties (@pxref{Property searches}).}. The list of matches may then
+become very long. If you only want to see the first tags match in a subtree,
+configure the variable @code{org-tags-match-list-sublevels}.
@node Setting tags, Tag searches, Tag inheritance, Tags
@section Setting tags
@@ -3886,6 +3975,8 @@
@item address@hidden/@key{right}
Switch to the next/previous allowed value of the field. For this, you
have to have specified allowed values for a property.
address@hidden 1..9,0
+Directly select the nth allowed value, @kbd{0} selects the 10th value.
@kindex n
@kindex p
@itemx n / p
@@ -3930,6 +4021,7 @@
this @code{columnview} dynamic block (@pxref{Dynamic blocks}). The frame
of this block looks like this:
address@hidden #+BEGIN: columnview
@example
* The column view
#+BEGIN: columnview :hlines 1 :id "label"
@@ -3948,8 +4040,10 @@
@example
local @r{use the tree in which the capture block is located}
global @r{make a global view, including all headings in the file}
-"label" @r{call column view in the tree that has and @code{:ID:}}
- @r{property with the value @i{label}}
+"label" @r{call column view in the tree that has an @code{:ID:}}
+ @r{property with the value @i{label}. You can use}
+ @address@hidden org-id-copy} to create a globally unique ID for}
+ @r{the current entry and copy it to the kill-ring.}
@end example
@item :hlines
When @code{t}, insert a hline after every line. When a number N, insert
@@ -4215,6 +4309,8 @@
the nth such day. E.g.
@example
++0 --> today
+. --> today
+4d --> four days from today
+4 --> same as above
+2w --> two weeks from today
@@ -4411,6 +4507,15 @@
happen in the line directly following the headline. Any CLOSED
timestamp will be removed. When called with a prefix argument, remove
the scheduling date from the entry.
address@hidden
address@hidden C-c C-x C-k
address@hidden k a
address@hidden k s
address@hidden C-c C-x C-k
+Mark the current entry for agenda action. After you have marked the entry
+like this, you can open the agenda or the calendar to find an appropriate
+date. With the cursor on the selected date, press @kbd{k s} or @kbd{k d} to
+schedule the marked item.
@end table
@node Repeated tasks, , Inserting deadline/schedule, Deadlines and scheduling
@@ -4545,6 +4650,7 @@
at an existing clock table, just update it. When called with a prefix
argument, jump to the first clock report in the current document and
update it.
address@hidden #+BEGIN: clocktable
@example
#+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file
#+END: clocktable
@@ -4620,7 +4726,7 @@
the agenda (@pxref{Weekly/daily agenda}) to show which tasks have been
worked on or closed during a day.
address@hidden Effort estimates
address@hidden Effort estimates, , Clocking work time, Dates and Times
@section Effort estimates
@cindex Effort estimates
@@ -4655,7 +4761,7 @@
If you switch to column view in the daily/weekly agenda, the effort column
will summarize the estimated work effort for each address@hidden note
the pitfalls of summing hierarchical data in a flat list (@pxref{Agenda
-column view}.}, and you can use this to find space in your schedule. To get
+column view}).}, and you can use this to find space in your schedule. To get
an overview of the entire part of the day that is committed, you can set the
option @code{org-agenda-columns-add-appointments-to-effort-sum}. The
appointments on a day that take place over a specified time interval will
@@ -4705,6 +4811,11 @@
use two prefix arguments, Org jumps to the location where the last
remember note was stored.
+You can also call @code{org-remember} in a special way from the agenda,
+using the @kbd{k r} key combination. With this access, any time stamps
+inserted by the selected remember template (see below) will default to
+the cursor date in the agenda, rather than to the current date.
+
@node Remember templates, Storing notes, Setting up Remember, Remember
@section Remember templates
@cindex templates, for remember
@@ -4724,26 +4835,29 @@
@noindent In these entries, the first string is just a name, and the
character specifies how to select the template. It is useful if the
-character is also the first letter of the name. The next string
-specifies the template. Two more (optional) strings give the file in
-which, and the headline under which the new note should be stored. The
-file (if not present or @code{nil}) defaults to
address@hidden, the heading to
address@hidden If the file name is not an
-absolute path, it will be interpreted relative to @code{org-directory}.
-
-An optional sixth element specifies the contexts in which the user can
-select the template. This element can be either a list of major modes
-or a function. @code{org-remember} will first check whether the function
-returns @code{t} or if we are in any of the listed major mode, and select
-the template accordingly.
+character is also the first letter of the name. The next string specifies
+the template. Two more (optional) strings give the file in which, and the
+headline under which the new note should be stored. The file (if not present
+or @code{nil}) defaults to @code{org-default-notes-file}, the heading to
address@hidden If the file name is not an absolute
+path, it will be interpreted relative to @code{org-directory}. The heading
+can also be the symbols @code{top} or @code{bottom} to send note as level 1
+entries to the beginning or end of the file, respectively.
+
+An optional sixth element specifies the contexts in which the user can select
+the template. This element can be a list of major modes or a function.
address@hidden will first check whether the function returns @code{t} or
+if we are in any of the listed major mode, and exclude templates fo which
+this condition is not fulfilled. Templates that do not specify this element
+at all, or that use @code{nil} or @code{t} as a value will always be
+selectable.
So for example:
@example
(setq org-remember-templates
'(("Bug" ?b "* BUG %?\n %i\n %a" "~/org/BUGS.org" "Bugs" (emacs-lisp-mode))
- ("Journal" ?j "* %U %?\n\n %i\n %a" "~/org/JOURNAL.org" my-check)
+ ("Journal" ?j "* %U %?\n\n %i\n %a" "~/org/JOURNAL.org" "X" my-check)
("Idea" ?i "* address@hidden@}\n %i\n %a" "~/org/JOURNAL.org" "New
Ideas")))
@end example
@@ -4752,8 +4866,8 @@
available when the function @code{my-check} returns @code{t}. The third
template will be proposed in any context.
-When you call @kbd{M-x remember} (or @kbd{M-x org-remember}) to remember
-something, org will prompt for a key to select the template (if you have
+When you call @kbd{M-x org-remember} (or @kbd{M-x remember}) to remember
+something, Org will prompt for a key to select the template (if you have
more than one template) and then prepare the buffer like
@example
* TODO
@@ -4768,16 +4882,16 @@
@r{You may specify a default value and a completion table with}
@address@hidden|default|completion2|address@hidden
@r{The arrow keys access a prompt-specific history.}
+%a @r{annotation, normally the link created with
@code{org-store-link}}
+%A @r{like @code{%a}, but prompt for the description part}
+%i @r{initial content, the region when remember is called with C-u.}
+ @r{The entire text will be indented like @code{%i} itself.}
%t @r{time stamp, date only}
%T @r{time stamp with date and time}
%u, %U @r{like the above, but inactive time stamps}
%^t @r{like @code{%t}, but prompt for date. Similarly @code{%^T},
@code{%^u}, @code{%^U}}
@r{You may define a prompt like @address@hidden@}t}}
%n @r{user name (taken from @code{user-full-name})}
-%a @r{annotation, normally the link created with
@code{org-store-link}}
-%A @r{like @code{%a}, but prompt for the description part}
-%i @r{initial content, the region when remember is called with C-u.}
- @r{The entire text will be indented like @code{%i} itself.}
%c @r{Current kill ring head.}
%x @r{Content of the X clipboard.}
%^C @r{Interactive selection of which kill or clip to use.}
@@ -4789,6 +4903,7 @@
%(sexp) @r{evaluate elisp @code{(sexp)} and replace with the result}
%! @r{immediately store note after completing the template}
@r{(skipping the @kbd{C-c C-c} that normally triggers storing)}
+%& @r{jump to target location immediately after storing note}
@end example
@noindent
@@ -4828,14 +4943,20 @@
@node Storing notes, Refiling notes, Remember templates, Remember
@section Storing notes
-When you are finished preparing a note with @i{remember}, you have to
-press @kbd{C-c C-c} to file the note away. The handler will store the
-note in the file and under the headline specified in the template, or it
-will use the default file and headlines. The window configuration will
-be restored, sending you back to the working context before the call to
address@hidden To re-use the location found during the last call to
address@hidden, exit the remember buffer with @kbd{C-u C-u C-c C-c},
-i.e. specify a double prefix argument to @kbd{C-c C-c}.
+When you are finished preparing a note with @i{remember}, you have to press
address@hidden C-c} to file the note away. If you have started the clock in the
+remember buffer, you will first be asked if you want to clock out
address@hidden avoid this query, configure the variable
address@hidden If you answer @kbd{n}, the clock
+will continue to run after the note is filed away.
+
+The handler will then store the note in the file and under the headline
+specified in the template, or it will use the default file and headlines.
+The window configuration will be restored, sending you back to the working
+context before the call to @code{remember}. To re-use the location found
+during the last call to @code{remember}, exit the remember buffer with
address@hidden C-u C-c C-c}, i.e. specify a double prefix argument to @kbd{C-c
+C-c}.
If you want to store the note directly to a different place, use
@kbd{C-u C-c C-c} instead to exit address@hidden the
@@ -4898,7 +5019,9 @@
address@hidden By default, all level 1 headlines in the current buffer are
considered to be targets, but you can have more complex definitions
across a number of files. See the variable @code{org-refile-targets}
-for details.
+for details. If you would like to select a location via a file-pathlike
+completion along the outline path, see the variable
address@hidden
@kindex C-u C-c C-w
@item C-u C-c C-w
Use the refile interface to jump to a heading.
@@ -5696,13 +5819,13 @@
@c
@kindex A
@item A
-Move the subtree correspoding to the current entry to its @emph{Archive
+Move the subtree corresponding to the current entry to its @emph{Archive
Sibling}.
@c
@kindex $
@item $
Archive the subtree corresponding to the current headline. This means the
-entry will be moved to the configured archive locatin, most likely a
+entry will be moved to the configured archive location, most likely a
different file.
@c
@kindex T
@@ -5747,6 +5870,21 @@
@item C-c C-d
Set a deadline for this item.
@c
address@hidden k
address@hidden k
+Agenda actions, to set dates for selected items to the cursor date.
+This command also works in the calendar! The command prompts for an
+additonal key:
address@hidden
+m @r{Mark the entry at point for action. You can also make entries}
+ @r{in Org files with @kbd{C-c C-x C-k}.}
+d @r{Set the deadline of the marked entry to the date at point.}
+s @r{Schedule the marked entry at the date at point.}
+r @r{Call @code{org-remember} with the cursor date as default date.}
address@hidden example
+Press @kbd{r} afterwards to refresh the agenda and see the effect of the
+command.
address@hidden
@kindex address@hidden
@item address@hidden
Change the time stamp associated with the current line by one day into the
@@ -6554,8 +6692,425 @@
Org mode can also produce extracts in the iCalendar format. Currently
Org mode only supports export, not import of these different formats.
-When exporting, Org mode uses special conventions to enrich the output
-produced. @xref{Text interpretation}, for more details.
address@hidden
+* Markup rules:: Which structures are recognized?
+* Export options:: Per-file export settings
+* The export dispatcher:: How to access exporter commands
+* ASCII export:: Exporting to plain ASCII
+* HTML export:: Exporting to HTML
+* LaTeX export:: Exporting to LaTeX
+* XOXO export:: Exporting to XOXO
+* iCalendar export:: Exporting in iCalendar format
address@hidden menu
+
address@hidden Markup rules, Export options, Exporting, Exporting
address@hidden Markup rules
+
+When exporting Org mode documents, the exporter tries to reflect the
+structure of the document as accurately as possible in the back-end. Since
+export targets like HTML or address@hidden allow much richer formatting, Org
mode
+has rules how to prepare text for rich export. This section summarizes the
+markup rule used in an Org mode buffer.
+
address@hidden
+* Document title:: How the document title is determined
+* Headings and sections:: The main structure of the exported document
+* Table of contents:: If, where, how to create a table of contents
+* Initial text:: Text before the first headline
+* Lists:: Plain lists are exported
+* Paragraphs:: What determines beginning and ending
+* Literal examples:: Source code and other examples
+* Include files:: Include the contents of a file during export
+* Tables exported:: Tables are exported richly
+* Footnotes:: Numbers like [1]
+* Emphasis and monospace:: To bold or not to bold
+* TeX macros and LaTeX fragments:: Create special, rich export.
+* Horizontal rules:: A line across the page
+* Comment lines:: Some lines will not be exported
address@hidden menu
+
address@hidden Document title, Headings and sections, Markup rules, Markup rules
address@hidden Document title
address@hidden document title, markup rules
+
address@hidden
+The title of the exported document is taken from the special line
+
address@hidden
+#+TITLE: This is the title of the document
address@hidden example
+
address@hidden
+If this line does not exist, the title is derived from the first non-empty,
+non-comment line in the buffer. If no such line exists, or if you have
+turned off exporting of the text before the first headline (see below), the
+title will be the file name without extension.
+
+If you are exporting only a subtree by marking is as the region, the heading
+of the subtree will become the title of the document. If the subtree has a
+property @code{EXPORT_TITLE}, that will take precedence.
+
address@hidden Headings and sections, Table of contents, Document title, Markup
rules
address@hidden Headings and sections
address@hidden headings and sections, markup rules
+
+The outline structure of the document as described in @ref{Document
+Structure} forms the basis for defining sections of the exported document.
+However, since the outline structure is also used for (for example) lists of
+tasks, only the first three outline levels will be used as headings. Deeper
+levels will become itemized lists. You can change the location of this
+switch, globally by setting the variable @code{org-headline-levels}, or on a
+per file basis with a line
+
address@hidden
+#+OPTIONS: H:4
address@hidden example
+
address@hidden Table of contents, Initial text, Headings and sections, Markup
rules
address@hidden Table of contents
address@hidden table of contents, markup rules
+
+The table of contents is normally inserted directly before the first headline
+of the file. If you would like to get it to a different location, insert the
+string @code{[TABLE-OF-CONTENTS]} on a line by itself at the desired
+location. The depth of the table of contents is by default the same as the
+number of headline levels, but you can choose a smaller number or turn off
+the table of contents entirely by configuring the variable
address@hidden, or on a per-file basis with a line like
+
address@hidden
+#+OPTIONS: toc:2 (only to two levels in TOC)
+#+OPTIONS: toc:nil (no TOC at all)
address@hidden example
+
address@hidden Initial text, Lists, Table of contents, Markup rules
address@hidden Text before the first headline
address@hidden text before first headline, markup rules
address@hidden #+TEXT
+
+Org mode normally exports the text before the first headline, and even uses
+the first line as the document title. The text will be fully marked up. If
+you need to include literal HTML or address@hidden code, use the special
constructs
+described below in the sections for the individual exporters.
+
+Some people like to use the space before the first headline for setup and
+internal links and therefore would like to control the exported text before
+the first headline in a different way. You can do so by setting the variable
address@hidden to @code{t}. On a per-file
+basis, you can get the same effect with @samp{#+OPTIONS: skip:t}.
+
address@hidden
+If you still want to have some text before the first headline, use the
address@hidden construct:
+
address@hidden
+#+OPTIONS: skip:t
+#+TEXT: This text will go before the *first* headline.
+#+TEXT: [TABLE-OF-CONTENTS]
+#+TEXT: This goes between the table of contents and the first headline
address@hidden example
+
address@hidden Lists, Paragraphs, Initial text, Markup rules
address@hidden Lists
address@hidden lists, markup rules
+
+Plain lists as described in @ref{Plain lists} are translated to the back-ends
+syntax for such lists. Most back-ends support unordered, ordered, and
+description lists.
+
address@hidden Paragraphs, Literal examples, Lists, Markup rules
address@hidden Paragraphs, line breaks, and quoting
address@hidden paragraphs, markup rules
+
+Paragraphs are separated by at least one empty line. If you need to enforce
+a line break within a paragraph, use @samp{\\} at the end of a line.
+
+To keep the line breaks in a region, but otherwise use normal formatting, you
+can use this construct, which can also be used to format poetry.
+
address@hidden
+#+BEGIN_VERSE
+Everything should be made as simple as possible,
+but not any simpler -- Albert Einstein
+#+END_VERSE
address@hidden example
+
+When quoting a passage from another document, it is customary to format this
+as a paragraph that is indented on both the left and the right margin. You
+can include quotations in Org mode documents like this:
+
address@hidden
+#+BEGIN_QUOTE
+Everything should be made as simple as possible,
+but not any simpler -- Albert Einstein
+#+END_QUOTE
address@hidden example
+
+
address@hidden Literal examples, Include files, Paragraphs, Markup rules
address@hidden Literal examples
address@hidden literal examples, markup rules
+
+You can include literal examples that should not be subjected to
+markup. Such examples will be typeset in monospace, so this is well suited
+for source code and similar examples.
address@hidden #+BEGIN_EXAMPLE
+
address@hidden
+#+BEGIN_EXAMPLE
+Some example from a text file.
+#+END_EXAMPLE
address@hidden example
+
+For simplicity when using small examples, you can also start the example
+lines with a colon:
+
address@hidden
+: Some example from a text file.
address@hidden example
+
address@hidden formatting source code, markup rules
+If the example is source code from a programming language, or any other text
+that can be marked up by font-lock in Emacs, you can ask for the example to
+look like the fontified Emacs address@hidden this works only for
+the HTML back-end, and requires the @file{htmlize.el} package version 1.34 or
+later.}. This is done with the @samp{src} block, where you also need to
+specify the name of the major mode that should be used to fontify the
+example:
address@hidden #+BEGIN_SRC
+
address@hidden
+#+BEGIN_SRC emacs-lisp
+(defun org-xor (a b)
+ "Exclusive or."
+ (if a (not b) b))
+#+END_SRC
address@hidden example
+
address@hidden @kbd
address@hidden C-c '
address@hidden C-c '
+Edit the source code example at point in its native mode. This works by
+switching to an indirect buffer, narrowing the buffer and switching to the
+other mode. You need to exit by pressing @kbd{C-c '} again.
address@hidden table
+
+
address@hidden Include files, Tables exported, Literal examples, Markup rules
address@hidden Include files
address@hidden include files, markup rules
+
+During export, you can include the content of another file. For example, to
+include your .emacs file, you could use:
address@hidden #+INCLUDE
+
address@hidden
+#+INCLUDE: "~/.emacs" src emacs-lisp
address@hidden example
+
+The optional second and third parameter are the markup (@samp{quote},
address@hidden, or @samp{src}), and, if the markup is @samp{src}, the
+language for formatting the contents. The markup is optional, if it is not
+given, the text will be assumed to be in Org mode format and will be
+processed normally.
+
address@hidden @kbd
address@hidden C-c '
address@hidden C-c '
+Visit the include file at point.
address@hidden table
+
address@hidden Tables exported, Footnotes, Include files, Markup rules
address@hidden Tables
address@hidden tables, markup rules
+
+Both the native Org mode tables (@pxref{Tables}) and tables formatted with
+the @file{table.el} package will be exported properly. For Org mode tables,
+the lines before the first horizontal separator line will become table header
+lines.
+
address@hidden Footnotes, Emphasis and monospace, Tables exported, Markup rules
address@hidden Footnotes
address@hidden footnotes, markup rules
address@hidden @file{footnote.el}
+
address@hidden C-c !
+Numbers in square brackets are treated as footnote markers, and lines
+starting with such a marker are interpreted as the footnote itself. You can
+use the Emacs package @file{footnote.el} to create address@hidden
address@hidden package uses @kbd{C-c !} to invoke its commands. This
+binding conflicts with the Org mode command for inserting inactive time
+stamps. You could use the variable @code{footnote-prefix} to switch
+footnotes commands to another key. Or, if you are too used to this binding,
+you could use @code{org-replace-disputed-keys} and @code{org-disputed-keys}
+to change the settings in Org.}. For example:
+
address@hidden
+The Org homepage[1] now looks a lot better than it used to.
+
+[1] The link is: http://orgmode.org
address@hidden example
+
address@hidden Emphasis and monospace, TeX macros and LaTeX fragments,
Footnotes, Markup rules
address@hidden Emphasis and monospace
+
address@hidden underlined text, markup rules
address@hidden bold text, markup rules
address@hidden italic text, markup rules
address@hidden verbatim text, markup rules
address@hidden code text, markup rules
address@hidden strike-through text, markup rules
+You can make words @b{*bold*}, @i{/italic/}, _underlined_, @code{=code=}
+and @code{~verbatim~}, and, if you must, @samp{+strike-through+}. Text
+in the code and verbatim string is not processed for Org mode specific
+syntax, it is exported verbatim.
+
address@hidden TeX macros and LaTeX fragments, Horizontal rules, Emphasis and
monospace, Markup rules
address@hidden @TeX{} macros and address@hidden fragments
address@hidden LaTeX fragments, markup rules
address@hidden TeX macros, markup rules
address@hidden HTML entities
address@hidden LaTeX entities
+
+A @TeX{}-like syntax is used to specify special characters. Where possible,
+these will be transformed into the native format of the exporter back-end.
+Strings like @code{\alpha} will be exported as @code{α} in the HTML
+output, and as @code{$\alpha$} in the address@hidden output. Similarly,
address@hidden will become @code{ } in HTML and @code{~} in address@hidden
+This applies for a large number of entities, with names taken from both HTML
+and address@hidden, see the variable @code{org-html-entities} for the complete
+list. If you are unsure about a name, use @address@hidden for completion
+after having types the backslash and maybe a few characters
+(@pxref{Completion}).
+
address@hidden fragments are converted into images for HTML export, and they are
+written literally into the address@hidden export. See also @ref{Embedded
LaTeX}.
+
+Finally, @samp{\-} is treated as a shy hyphen, and @samp{--}, @samp{---}, and
address@hidden are all converted into special commands creating hyphens of
+different lengths or a compact set of dots.
+
address@hidden Horizontal rules, Comment lines, TeX macros and LaTeX fragments,
Markup rules
address@hidden Horizontal rules
address@hidden horizontal rules, markup rules
+A line consisting of only dashes, and at least 5 of them, will be
+exported as a horizontal line (@samp{<hr/>} in HTML).
+
address@hidden Comment lines, , Horizontal rules, Markup rules
address@hidden Comment lines
address@hidden comment lines
address@hidden exporting, not
+
+Lines starting with @samp{#} in column zero are treated as comments and will
+never be exported. Also entire subtrees starting with the word
address@hidden will never be exported. Finally, regions surrounded by
address@hidden ... @samp{#+END_COMMENT} will not be exported.
+
address@hidden @kbd
address@hidden C-c ;
address@hidden C-c ;
+Toggle the COMMENT keyword at the beginning of an entry.
address@hidden table
+
address@hidden Export options, The export dispatcher, Markup rules, Exporting
address@hidden Export options
address@hidden options, for export
+
address@hidden completion, of option keywords
+The exporter recognizes special lines in the buffer which provide
+additional information. These lines may be put anywhere in the file.
+The whole set of lines can be inserted into the buffer with @kbd{C-c
+C-e t}. For individual lines, a good way to make sure the keyword is
+correct is to type @samp{#+} and then use @address@hidden completion
+(@pxref{Completion}).
+
address@hidden @kbd
address@hidden C-c C-e t
address@hidden C-c C-e t
+Insert template with export options, see example below.
address@hidden table
+
address@hidden #+TITLE:
address@hidden #+AUTHOR:
address@hidden #+DATE:
address@hidden #+EMAIL:
address@hidden #+LANGUAGE:
address@hidden #+TEXT:
address@hidden #+OPTIONS:
address@hidden #+LINK_UP:
address@hidden #+LINK_HOME:
address@hidden
+#+TITLE: the title to be shown (default is the buffer name)
+#+AUTHOR: the author (default taken from @code{user-full-name})
+#+DATE: A date, fixed, of a format string for @code{format-time-string}
+#+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 f:t TeX:t ...
+#+LINK_UP: the ``up'' link of an exported page
+#+LINK_HOME: the ``home'' link of an exported page
address@hidden example
+
address@hidden
+The OPTIONS line is a address@hidden you want to configure many options
+this way, you can use several OPTIONS lines.} form to specify export settings.
Here
+you can:
address@hidden headline levels
address@hidden section-numbers
address@hidden table of contents
address@hidden line-break preservation
address@hidden quoted HTML tags
address@hidden fixed-width sections
address@hidden tables
address@hidden @TeX{}-like syntax for sub- and superscripts
address@hidden footnotes
address@hidden special strings
address@hidden emphasized text
address@hidden @TeX{} macros
address@hidden address@hidden fragments
address@hidden author info, in export
address@hidden time info, in export
address@hidden
+H: @r{set the number of headline levels for export}
+num: @r{turn on/off section-numbers}
+toc: @r{turn on/off table of contents, or set level limit (integer)}
+\n: @r{turn on/off line-break-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. If}
+ @r{you write "^:@address@hidden", @address@hidden@}} will be
interpreted, but}
+ @r{the simple @code{a_b} will be left as it is.}
+-: @r{turn on/off conversion of special strings.}
+f: @r{turn on/off footnotes like this[1].}
+*: @r{turn on/off emphasized text (bold, italic, underlined)}
+TeX: @r{turn on/off simple @TeX{} macros in plain text}
+LaTeX: @r{turn on/off address@hidden fragments}
+skip: @r{turn on/off skipping the text before the first heading}
+author: @r{turn on/off inclusion of author name/email into exported file}
+timestamp: @r{turn on/off inclusion creation time into exported file}
+d: @r{turn on/off inclusion of drawers}
address@hidden example
+
+These options take effect in both the HTML and address@hidden export, except
+for @code{TeX} and @code{LaTeX}, which are respectively @code{t} and
address@hidden for the address@hidden export.
+
+When exporting only a single subtree by selecting it with @kbd{C-c @@} before
+calling an export command, the subtree can overrule some of the file's export
+settings with properties @code{EXPORT_FILE_NAME}, @code{EXPORT_TITLE},
address@hidden, and @code{EXPORT_OPTIONS}.
+
address@hidden The export dispatcher, ASCII export, Export options, Exporting
address@hidden The export dispatcher
address@hidden dispatcher, for export commands
+
+All export commands can be reached using the export dispatcher, which is a
+prefix key that prompts for an additional key specifying the command.
+Normally the entire file is exported, but if there is an active region that
+contains one outline tree, the first heading is used as document title and
+the subtrees are exported.
@table @kbd
@kindex C-c C-e
@@ -6566,6 +7121,10 @@
@code{org-export-run-in-background} is set, Org will run the command in the
background if that seems useful for the specific command (i.e. commands that
write to a file).
address@hidden C-c C-e v
address@hidden C-c C-e v
+Like @kbd{C-c C-e}, but only export the text that is currently visible
+(i.e. not hidden by outline visibility).
@kindex C-u C-u C-c C-e
@item C-u C-u C-c C-e
Call an the exporter, but reverse the setting of
@@ -6573,16 +7132,7 @@
not set, or force processing in the current Emacs process if st.
@end table
address@hidden
-* ASCII export:: Exporting to plain ASCII
-* HTML export:: Exporting to HTML
-* LaTeX export:: Exporting to LaTeX
-* XOXO export:: Exporting to XOXO
-* iCalendar export:: Exporting in iCalendar format
-* Text interpretation:: How the exporter looks at the file
address@hidden menu
-
address@hidden ASCII export, HTML export, Exporting, Exporting
address@hidden ASCII export, HTML export, The export dispatcher, Exporting
@section ASCII export
@cindex ASCII export
@@ -6598,9 +7148,10 @@
Export as ASCII file. For an org file @file{myfile.org}, the ASCII file
will be @file{myfile.txt}. The file will be overwritten without
warning. If there is an active region, only the region will be
-exported. If the selected region is a single tree, the tree head will
+exported. If the selected region is a single address@hidden select the
+current subtree, use @kbd{C-c @@}.}, the tree head will
become the document title. If the tree head entry has or inherits an
address@hidden:EXPORT_FILE_NAME:} property, that name will be used for the
address@hidden property, that name will be used for the
export.
@kindex C-c C-e v a
@item C-c C-e v a
@@ -6635,7 +7186,7 @@
language, but with additional support for tables.
@menu
-* HTML Export commands:: How to invoke LaTeX export
+* HTML Export commands:: How to invoke HTML export
* Quoting HTML tags:: Using direct HTML in Org mode
* Links:: Transformation of links for HTML
* Images:: How to include images
@@ -6652,13 +7203,13 @@
@table @kbd
@kindex C-c C-e h
@item C-c C-e h
-Export as HTML file @file{myfile.html}. For an org file
address@hidden, the ASCII file will be @file{myfile.html}. The file
-will be overwritten without warning. If there is an active region, only
-the region will be exported. If the selected region is a single tree,
-the tree head will become the document title. If the tree head entry
-has or inherits an @code{:EXPORT_FILE_NAME:} property, that name will be
-used for the export.
+Export as HTML file @file{myfile.html}. For an org file @file{myfile.org},
+the ASCII file will be @file{myfile.html}. The file will be overwritten
+without warning. If there is an active region, only the region will be
+exported. If the selected region is a single address@hidden select the
+current subtree, use @kbd{C-c @@}.}, the tree head will become the document
+title. If the tree head entry has or inherits an @code{EXPORT_FILE_NAME}
+property, that name will be used for the export.
@kindex C-c C-e b
@item C-c C-e b
Export as HTML file and immediately open it with a browser.
@@ -6716,6 +7267,7 @@
@end example
@noindent or
address@hidden #+BEGIN_HTML
@example
#+BEGIN_HTML
@@ -6818,19 +7370,20 @@
as well, press @kbd{?} for an overview of the available keys). The second
view type is a @emph{folding} view much like Org provides it inside Emacs.
The script is available at @url{http://orgmode.org/org-info.js} and you can
-find the documentation for it at @url{http://orgmode.org/org-infojs.html}.
-We are serving the script from our site, but if you use it a lot, you might
-not want to be dependent on @url{orgmode.org} and prefer to install a local
-copy on your own web server.
+find the documentation for it at
address@hidden://orgmode.org/worg/code/org-info-js/org-info.js.html}. We are
+serving the script from our site, but if you use it a lot, you might not want
+to be dependent on @url{orgmode.org} and prefer to install a local copy on
+your own web server.
-To use the script, you need to make sure that the @file{org-infojs.el} module
+To use the script, you need to make sure that the @file{org-jsinfo.el} module
gets loaded. It should be loaded by default, try @kbd{M-x customize-variable
@key{RET} org-modules @key{RET}} to convince yourself that this is indeed the
case. All it then takes to make use of the program is adding a single line
to the Org file:
@example
-#+INFOSJ_OPT: view:info toc:nil
+#+INFOJS_OPT: view:info toc:nil
@end example
@noindent
@@ -6842,7 +7395,7 @@
path: @r{The path to the script. The default is to grab the script from}
@address@hidden://orgmode.org/org-info.js}, but you might want to
have}
@r{a local copy and use a path like @samp{../scripts/org-info.js}.}
-view: @r{Initial view when website is first shown. Possible values are}
+view: @r{Initial view when website is first shown. Possible values are:}
info @r{Info-like interface with one section per page.}
overview @r{Folding interface, initially showing only top-level.}
content @r{Folding interface, starting with all headlines visible.}
@@ -6856,6 +7409,8 @@
@r{Even when @code{nil}, you can always get to the toc with @kbd{i}.}
tdepth: @r{The depth of the table of contents. The defaults are taken from}
@r{the variables @code{org-headline-levels} and
@code{org-export-with-toc}.}
+ftoc: @r{Does the css of the page specify a fixed position for the toc?}
+ @r{If yes, the toc will never be displayed as a section.}
ltoc: @r{Should there be short contents (children) in each section?}
mouse: @r{Headings are highlighted when the mouse is over them. Should be}
@address@hidden (default) or a background color like @samp{#cccccc}.}
@@ -6885,7 +7440,13 @@
@table @kbd
@kindex C-c C-e l
@item C-c C-e l
-Export as address@hidden file @file{myfile.tex}.
+Export as address@hidden file @file{myfile.tex}. For an org file
address@hidden, the ASCII file will be @file{myfile.tex}. The file will
+be overwritten without warning. If there is an active region, only the
+region will be exported. If the selected region is a single address@hidden
+select the current subtree, use @kbd{C-c @@}.}, the tree head will become the
+document title. If the tree head entry has or inherits an
address@hidden property, that name will be used for the export.
@kindex C-c C-e L
@item C-c C-e L
Export to a temporary buffer, do not create a file.
@@ -6933,6 +7494,7 @@
@end example
@noindent or
address@hidden #+BEGIN_LaTeX
@example
#+BEGIN_LaTeX
@@ -6940,8 +7502,6 @@
#+END_LaTeX
@end example
-
-
@node Sectioning structure, , Quoting LaTeX code, LaTeX export
@subsection Sectioning structure
@cindex LaTeX class
@@ -6973,7 +7533,7 @@
Export only the visible part of the document.
@end table
address@hidden iCalendar export, Text interpretation, XOXO export, Exporting
address@hidden iCalendar export, , XOXO export, Exporting
@section iCalendar export
@cindex iCalendar export
@@ -6985,6 +7545,16 @@
iCalendar format. If you also want to have TODO entries included in the
export, configure the variable @code{org-icalendar-include-todo}.
+The iCalendar standard requires each entry to have a globally unique
+identifier (UID). Org creates these identifiers during export. If you set
+the variable @code{org-icalendar-store-UID}, the UID will be stored in the
address@hidden:ID:} property of the entry and re-used next time you report this
+entry. Since a single entry can give rise to multiple iCalendar entries (as
+a timestamp, a deadline, a scheduled item, and as a TODO item), Org adds
+prefixes to the UID, depending on what triggered the inclusion of the entry.
+In this way the UID remains unique, but a synchronization program can still
+figure out from which entry all the different instances originate.
+
@table @kbd
@kindex C-c C-e i
@item C-c C-e i
@@ -7010,294 +7580,6 @@
How this calendar is best read and updated, depends on the application
you are using. The FAQ covers this issue.
-
address@hidden Text interpretation, , iCalendar export, Exporting
address@hidden Text interpretation by the exporter
-
-The exporter backends interpret additional structure in the Org file
-in order to produce better output.
-
address@hidden
-* Comment lines:: Some lines will not be exported
-* Initial text:: Text before the first headline
-* Footnotes:: Numbers like [1]
-* Quoted examples:: Inserting quoted chunks of text
-* Enhancing text:: Subscripts, symbols and more
-* Export options:: How to influence the export settings
address@hidden menu
-
address@hidden Comment lines, Initial text, Text interpretation, Text
interpretation
address@hidden Comment lines
address@hidden comment lines
address@hidden exporting, not
-
-Lines starting with @samp{#} in column zero are treated as comments
-and will never be exported. Also entire subtrees starting with the
-word @samp{COMMENT} will never be exported.
-
address@hidden @kbd
address@hidden C-c ;
address@hidden C-c ;
-Toggle the COMMENT keyword at the beginning of an entry.
address@hidden table
-
address@hidden Initial text, Footnotes, Comment lines, Text interpretation
address@hidden Text before the first headline
-
-Org mode normally ignores any text before the first headline when
-exporting, leaving this region for internal links to speed up navigation
-etc. However, in publishing-oriented files, you might want to have some
-text before the first headline, like a small introduction, special HTML
-code with a navigation bar, etc. You can ask to have this part of the
-file exported as well by setting the variable
address@hidden to @code{nil}. On a
-per-file basis, you can get the same effect with
-
address@hidden
-#+OPTIONS: skip:nil
address@hidden example
-
-The text before the first headline will be fully processed
-(@pxref{Enhancing text}), and the first non-comment line becomes the
-title of the exported document. If you need to include literal HTML,
-use the special constructs described in @ref{Quoting HTML tags}. The
-table of contents is normally inserted directly before the first
-headline of the file. If you would like to get it to a different
-location, insert the string @code{[TABLE-OF-CONTENTS]} on a line by
-itself at the desired location.
-
-Finally, if you want to use the space before the first headline for
-internal purposes, but @emph{still} want to place something before the
-first headline when exporting the file, you can use the @code{#+TEXT}
-construct:
-
address@hidden
-#+OPTIONS: skip:t
-#+TEXT: This text will go before the *first* headline.
-#+TEXT: We place the table of contents here:
-#+TEXT: [TABLE-OF-CONTENTS]
-#+TEXT: This goes between the table of contents and the first headline
address@hidden example
-
address@hidden Footnotes, Quoted examples, Initial text, Text interpretation
address@hidden Footnotes
address@hidden footnotes
address@hidden @file{footnote.el}
-
-Numbers in square brackets are treated as footnotes, so that you can use
-the Emacs package @file{footnote.el} to create footnotes. For example:
-
address@hidden
-The Org homepage[1] clearly needs help from
-a good web designer.
-
-[1] The link is: http://orgmode.org
address@hidden example
-
address@hidden
address@hidden C-c !
-Note that the @file{footnote} package uses @kbd{C-c !} to invoke its
-commands. This binding conflicts with the Org mode command for
-inserting inactive time stamps. You could use the variable
address@hidden to switch footnotes commands to another key. Or,
-if you are too used to this binding, you could use
address@hidden and @code{org-disputed-keys} to change
-the settings in Org.
-
address@hidden Quoted examples, Enhancing text, Footnotes, Text interpretation
address@hidden Quoted examples
address@hidden quoted examples
address@hidden examples, quoted
address@hidden text, fixed width
address@hidden fixed width text
-
-When writing technical documents, you often need to insert examples that
-are not further interpreted by Org mode. For historical reasons, there
-are several ways to do this:
-
address@hidden @bullet
address@hidden
-If a headline starts with the word @samp{QUOTE}, the text below the
-headline will be typeset as fixed-width, to allow quoting of computer
-codes etc.
address@hidden
-Lines starting with @samp{:} are also typeset in fixed-width font.
address@hidden @kbd
address@hidden C-c :
address@hidden C-c :
-Toggle fixed-width for entry (QUOTE) or region, see below.
address@hidden table
address@hidden
-Finally, text between
address@hidden
-#+BEGIN_EXAMPLE
-quoted text
-#+END_EXAMPLE
address@hidden example
-will also be exported in this way.
address@hidden itemize
-
-
address@hidden Enhancing text, Export options, Quoted examples, Text
interpretation
address@hidden Enhancing text for export
address@hidden enhancing text
address@hidden richer text
-
-Some of the export backends of Org mode allow for sophisticated text
-formatting, this is true in particular for the HTML and address@hidden
-backends. Org mode has a number of typing conventions that allow to
-produce a richly formatted output.
-
address@hidden @bullet
-
address@hidden hand-formatted lists
address@hidden lists, hand-formatted
address@hidden
-Plain lists @samp{-}, @samp{*} or @samp{+} as bullet, or with @samp{1.}
-or @samp{2)} as enumerator will be recognized and transformed if the
-backend supports lists. See @xref{Plain lists}.
-
address@hidden underlined text
address@hidden bold text
address@hidden italic text
address@hidden verbatim text
address@hidden
-You can make words @b{*bold*}, @i{/italic/}, _underlined_, @code{=code=}
-and @code{~verbatim~}, and, if you must, @samp{+strikethrough+}. Text
-in the code and verbatim string is not processed for Org mode specific
-syntax, it is exported verbatim.
-
address@hidden horizontal rules, in exported files
address@hidden
-A line consisting of only dashes, and at least 5 of them, will be
-exported as a horizontal line (@samp{<hr/>} in HTML).
-
address@hidden LaTeX fragments, export
address@hidden TeX macros, export
address@hidden
-Many @TeX{} macros and entire address@hidden fragments are converted into HTML
-entities or images (@pxref{Embedded LaTeX}).
-
address@hidden tables, export
address@hidden
-Tables are transformed into native tables under the exporter, if the
-export backend supports this. Data fields before the first horizontal
-separator line will be formatted as table header fields.
-
address@hidden fixed width
address@hidden
-If a headline starts with the word @samp{QUOTE}, the text below the
-headline will be typeset as fixed-width, to allow quoting of computer
-codes etc. Lines starting with @samp{:} are also typeset in fixed-width
-font.
address@hidden @kbd
address@hidden C-c :
address@hidden C-c :
-Toggle fixed-width for entry (QUOTE) or region, see below.
address@hidden table
-Finally, text between
address@hidden
-#+BEGIN_EXAMPLE
-quoted text
-#+END_EXAMPLE
address@hidden example
-will also be exported in this way.
-
address@hidden linebreak, forced
address@hidden
-A double backslash @emph{at the end of a line} enforces a line break at
-this position.
-
address@hidden HTML entities, LaTeX entities
address@hidden
-Strings like @code{\alpha} will be exported as @code{α}, in the
-HTML output. These strings are exported as @code{$\alpha$} in the
address@hidden output. Similarly, @code{\nbsp} will become @code{ } in
-HTML and in address@hidden This applies for a long list of entities, see
-the variable @code{org-html-entities} for the complete list.
address@hidden FIXME
address@hidden itemize
-
-If these conversions conflict with your habits of typing ASCII text,
-they can all be turned off with corresponding variables. See the
-customization group @code{org-export-general}, and the following section
-which explains how to set export options with special lines in a
-buffer.
-
-
address@hidden Export options, , Enhancing text, Text interpretation
address@hidden Export options
address@hidden options, for export
-
address@hidden completion, of option keywords
-The exporter recognizes special lines in the buffer which provide
-additional information. These lines may be put anywhere in the file.
-The whole set of lines can be inserted into the buffer with @kbd{C-c
-C-e t}. For individual lines, a good way to make sure the keyword is
-correct is to type @samp{#+} and then use @address@hidden completion
-(@pxref{Completion}).
-
address@hidden @kbd
address@hidden C-c C-e t
address@hidden C-c C-e t
-Insert template with export options, see example below.
address@hidden table
-
address@hidden
-#+TITLE: the title to be shown (default is the buffer name)
-#+AUTHOR: the author (default taken from @code{user-full-name})
-#+DATE: A date, fixed, of a format string for @code{format-time-string}
-#+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 f:t TeX:t ...
address@hidden example
-
address@hidden
-The OPTIONS line is a compact form to specify export settings. Here
-you can:
address@hidden headline levels
address@hidden section-numbers
address@hidden table of contents
address@hidden linebreak preservation
address@hidden quoted HTML tags
address@hidden fixed-width sections
address@hidden tables
address@hidden @TeX{}-like syntax for sub- and superscripts
address@hidden footnotes
address@hidden special strings
address@hidden emphasized text
address@hidden @TeX{} macros
address@hidden address@hidden fragments
address@hidden author info, in export
address@hidden time info, in export
address@hidden
-H: @r{set the number of headline levels for export}
-num: @r{turn on/off section-numbers}
-toc: @r{turn on/off table of contents, or set level limit (integer)}
-\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. If}
- @r{you write "^:@address@hidden", @address@hidden@}} will be
interpreted, but}
- @r{the simple @code{a_b} will be left as it is.}
--: @r{turn on/off conversion of special strings.}
-f: @r{turn on/off foototes like this[1].}
-*: @r{turn on/off emphasized text (bold, italic, underlined)}
-TeX: @r{turn on/off simple @TeX{} macros in plain text}
-LaTeX: @r{turn on/off address@hidden fragments}
-skip: @r{turn on/off skipping the text before the first heading}
-author: @r{turn on/off inclusion of author name/email into exported file}
-timestamp: @r{turn on/off inclusion creation time into exported file}
-d: @r{turn on/off inclusion of drawers}
address@hidden example
-
-These options take effect in both the HTML and address@hidden export, except
-for @code{TeX} and @code{LaTeX}, which are respectively @code{t} and
address@hidden for the address@hidden export.
-
@node Publishing, Miscellaneous, Exporting, Top
@chapter Publishing
@cindex publishing
@@ -7383,8 +7665,11 @@
@item @code{:publishing-directory}
@tab Directory (possibly remote) where output files will be published.
@item @code{:preparation-function}
address@hidden Function called before starting publishing process, for example
to
address@hidden Function called before starting the publishing process, for
example to
run @code{make} for updating files to be published.
address@hidden @code{:completion-function}
address@hidden Function called after finishing the publishing process, for
example to
+change permissions of the resulting files.
@end multitable
@noindent
@@ -7651,7 +7936,7 @@
functions normally only publish changed files. You can override this and
force publishing of all files by giving a prefix argument.
address@hidden Miscellaneous, Extensions and Hacking, Publishing, Top
address@hidden Miscellaneous, Extensions, Publishing, Top
@chapter Miscellaneous
@menu
@@ -7769,6 +8054,9 @@
line set the local variable @code{org-table-formula-constants-local}.
The global version of this variable is
@code{org-table-formula-constants}.
address@hidden #+FILETAGS: :tag1:tag2:tag3:
+Set tags that can be inherited by any entry in the file, including the
+top-level entries.
@item #+DRAWERS: NAME1 .....
Set the file-local set of drawers. The corresponding global variable is
@code{org-drawers}.
@@ -7783,6 +8071,14 @@
@item #+PROPERTY: Property_Name Value
This line sets a default inheritance value for entries in the current
buffer, most useful for specifying the allowed values of a property.
address@hidden #+SETUPFILE: file
+This line defines a file that holds more in-buffer setup. Normally this is
+entirely ignored. Only when the buffer is parsed for option-setting lines
+(i.e. when starting Org mode for a file, when pressing @kbd{C-c C-c} in a
+settings line, or when exporting), then the contents of this file are parsed
+as if they had been included in the buffer. In particlar, the file can be
+any other Org mode file with internal setup. You can visit the file the
+cursor is in the line with @kbd{C-c '}.
@item #+STARTUP:
This line sets options to be used at startup of Org mode, when an
Org file is being visited. The first set of options deals with the
@@ -7828,10 +8124,10 @@
lognoteclock-out @r{record a note when clocking out}
nolognoteclock-out @r{don't record a note when clocking out}
@end example
-Here are the options for hiding leading stars in outline headings. The
-corresponding variables are @code{org-hide-leading-stars} and
address@hidden, both with a default setting @code{nil}
-(meaning @code{showstars} and @code{oddeven}).
+Here are the options for hiding leading stars in outline headings, and for
+indenting outlines. The corresponding variables are
address@hidden and @code{org-odd-levels-only}, both with a
+default setting @code{nil} (meaning @code{showstars} and @code{oddeven}).
@cindex @code{hidestars}, STARTUP keyword
@cindex @code{showstars}, STARTUP keyword
@cindex @code{odd}, STARTUP keyword
@@ -7839,6 +8135,8 @@
@example
hidestars @r{make all but one of the stars starting a headline invisible.}
showstars @r{show all stars starting a headline}
+indent @r{virtual indentation according to outline level}
+noindent @r{no virtual indentation according to outline level}
odd @r{allow only odd outline levels (1,3,...)}
oddeven @r{allow all outline levels}
@end example
@@ -7925,56 +8223,73 @@
@node Clean view, TTY keys, The very busy C-c C-c key, Miscellaneous
@section A cleaner outline view
@cindex hiding leading stars
address@hidden dynamic indentation
address@hidden odd-levels-only outlines
@cindex clean outline view
-Some people find it noisy and distracting that the Org headlines
-are starting with a potentially large number of stars. For example
-the tree from @ref{Headlines}:
+Some people find it noisy and distracting that the Org headlines are starting
+with a potentially large number of stars, and that text below the headlines
+is not indented. This is not really a problem when you are writing a book
+where the outline headings are really section headlines. However, in a more
+list-oriented outline, it is clear that an indented structure is a lot
+cleaner, as can be seen by comparing the two columns in the following
+example:
@example
-* Top level headline
-** Second level
-*** 3rd level
- some text
-*** 3rd level
- more text
-* Another top level headline
address@hidden
+* Top level headline | * Top level headline
+** Second level | * Second level
+*** 3rd level | * 3rd level
+some text | some text
+*** 3rd level | * 3rd level
+more text | more text
+* Another top level headline | * Another top level headline
address@hidden group
@end example
@noindent
-Unfortunately this is deeply ingrained into the code of Org and
-cannot be easily changed. You can, however, modify the display in such
-a way that all leading stars become invisible and the outline more easy
-to read. To do this, customize the variable
address@hidden like this:
+It is non-trivial to make such a look work in Emacs, but Org contains three
+separate features that, combined, achieve just that.
address@hidden
-(setq org-hide-leading-stars t)
address@hidden lisp
address@hidden
address@hidden
address@hidden of text below address@hidden
+You may indent text below each headline to make the left boundary line up
+with the headline, like
address@hidden
-or change this on a per-file basis with one of the lines (anywhere in
-the buffer)
address@hidden
+*** 3rd level
+ more text, now indented
address@hidden example
+
+A good way to get this indentation is by hand, and Org supports this with
+paragraph filling, line wrapping, and structure address@hidden also the
+variable @code{org-adapt-indentation}.} preserving or adapting the
+indentation appropriate. A different approach would be to have a way to
+automatically indent lines according to outline structure by adding overlays
+or text properties. But I have not yet found a robust and efficient way to
+do this in large files.
+
address@hidden
address@hidden leading address@hidden You can modify the display in such a way
that
+all leading stars become invisible. To do this in a global way, configure
+the variable @code{org-hide-leading-stars} or change this on a per-file basis
+with
@example
#+STARTUP: showstars
#+STARTUP: hidestars
@end example
address@hidden
-Press @kbd{C-c C-c} with the cursor in a @samp{STARTUP} line to activate
-the modifications.
-
-With stars hidden, the tree becomes:
+With hidden stars, the tree becomes:
@example
address@hidden
* Top level headline
* Second level
* 3rd level
- some text
- * 3rd level
- more text
-* Another top level headline
+ ...
address@hidden group
@end example
@noindent
@@ -7986,32 +8301,14 @@
stars are @i{almost} invisible, for example using the color
@code{grey90} on a white background.
-Things become cleaner still if you skip all the even levels and use only
-odd levels 1, 3, 5..., effectively adding two stars to go from one
-outline level to the next:
-
address@hidden
-* Top level headline
- * Second level
- * 3rd level
- some text
- * 3rd level
- more text
-* Another top level headline
address@hidden example
-
address@hidden
-In order to make the structure editing and export commands handle this
-convention correctly, use
-
address@hidden
-(setq org-odd-levels-only t)
address@hidden lisp
-
address@hidden
-or set this on a per-file basis with one of the following lines (don't
-forget to press @kbd{C-c C-c} with the cursor in the startup line to
-activate changes immediately).
address@hidden
+Things become cleaner still if you skip all the even levels and use only odd
+levels 1, 3, 5..., effectively adding two stars to go from one outline level
+to the next. In this way we get the outline view shown at the beginning of
+this section. In order to make the structure editing and export commands
+handle this convention correctly, configure the variable
address@hidden, or set this on a per-file basis with one of the
+following lines:
@example
#+STARTUP: odd
@@ -8022,6 +8319,7 @@
double-star-per-level convention with @kbd{M-x org-convert-to-odd-levels
RET} in that file. The reverse operation is @kbd{M-x
org-convert-to-oddeven-levels}.
address@hidden enumerate
@node TTY keys, Interaction, Clean view, Miscellaneous
@section Using Org on a tty
@@ -8240,39 +8538,108 @@
may use the command @code{org-table-iterate} (@kbd{C-u C-c *}) to
recalculate until convergence.
@item
-A single letter cannot be made bold, for example @samp{*a*}.
address@hidden
The exporters work well, but could be made more efficient.
@end itemize
address@hidden Extensions and Hacking, History and Acknowledgments,
Miscellaneous, Top
address@hidden Extensions, Hooks and Hacking
address@hidden Extensions, Hacking, Miscellaneous, Top
address@hidden Extensions
-This appendix lists extensions for Org written by other authors.
-It also covers some aspects where users can extend the functionality of
+This appendix lists the extension modules that have been written for Org.
+Many of these extensions live in the @file{contrib} directory of the Org
+distribution, others are available somewhere on the web.
+
address@hidden
+* Extensions in the contrib directory:: These come with the Org distro
+* Other extensions:: These you have to find on the web.
address@hidden menu
+
address@hidden Extensions in the contrib directory, Other extensions,
Extensions, Extensions
address@hidden Extensions in the @file{contrib} directory
+
address@hidden @asis
address@hidden @file{org-annotate-file.el} by @i{Philip Jackson}
+ Annotate a file with org syntax, in a separate file, with links back to
+ the annotated file.
address@hidden @file{org-annotation-helper.el} by @i{Bastien Guerry and Daniel
E. German}
+ Call @i{remember} directly from Firefox/Opera, or from Adobe Reader.
+ When activating a special link or bookmark, Emacs receives a trigger to
+ create a note with a link back to the website. Requires some setup, a
+ detailes description is in
+ @file{contrib/packages/org-annotation-helper}.
address@hidden @file{org-bookmark.el} by @i{Tokuya Kameshima}
+ Support for links to Emacs bookmarks.
address@hidden @file{org-depend.el} by @i{Carsten Dominik}
+ TODO dependencies for Org-mode. Make TODO state changes in one entry
+ trigger changes in another, or be blocked by the state of another
+ entry. Also, easily create chains of TODO items with exactly one
+ active item at any time.
address@hidden @file{org-elisp-symbol.el} by @i{Bastien Guerry}
+ Org links to emacs-lisp symbols. This can create annotated links that
+ exactly point to the definition location of a variable of function.
address@hidden @file{org-eval.el} by @i{Carsten Dominik}
+ The @code{<lisp>} tag, adapted from Emacs Wiki and Emacs Muse, allows
+ to include text in a document that is the result of evaluating some
+ code. Other scripting languages like @code{perl} can be supported with
+ this package as well.
address@hidden @file{org-expiry.el} by @i{Bastien Guerry}
+ Expiry mechanism for Org entries.
address@hidden @file{org-indent.el} by @i{Carsten Dominik}
+ Dynamic indentation of Org outlines. The plan is to indent an outline
+ according to level, but so far this is too hard for a proper and stable
+ implementation. Still, it works somewhat.
address@hidden @file{org-interactive-query.el} by @i{Christopher League}
+ Interactive modification of tags queries. After running a general
+ query in Org, this package allows to narrow down the results by adding
+ more tags or keywords.
address@hidden @file{org-mairix.el} by @i{Georg C. F. Greve}
+ Hook mairix search into Org for different MUAs.
address@hidden @file{org-man.el} by @i{Carsten Dominik}
+ Support for links to manpages in Org-mode.
address@hidden @file{org-mtags.el} by @i{Carsten Dominik}
+ Support for some Muse-like tags in Org-mode. This package allows you
+ to write @code{<example>} and @code{<src>} and other syntax copied from
+ Emacs Muse, right inside an Org file. The goal here is to make it easy
+ to publish the same file using either org-publish or Muse.
address@hidden @file{org-panel.el} by @i{Lennard Borgman}
+ Simplified and display-aided access to some Org commands.
address@hidden @file{org-registry.el} by @i{Bastien Guerry}
+ A registry for Org links, to find out from where links point to a given
+ file or location.
address@hidden @file{org2rem.el} by @i{Bastien Guerry}
+ Convert org appointments into reminders for the @file{remind} program.
address@hidden @file{org-screen.el} by @i{Andrew Hyatt}
+ Visit screen sessions through Org-mode links.
address@hidden @file{org-toc.el} by @i{Bastien Guerry}
+ Table of contents in a separate buffer, with fast access to sections
+ and easy visibility cycling.
address@hidden @file{orgtbl-sqlinsert.el} by @i{Jason Riedy}
+ Convert Org-mode tables to SQL insertions. Documentation for this can
+ be found on the Worg pages.
address@hidden table
+
+
address@hidden Other extensions, , Extensions in the contrib directory,
Extensions
address@hidden Other extensions
+
address@hidden BE DONE}
+
address@hidden Hacking, History and Acknowledgments, Extensions, Top
address@hidden Hacking
+
+This appendix covers some aspects where users can extend the functionality of
Org.
@menu
-* Extensions:: Existing 3rd-party extensions
* Adding hyperlink types:: New custom link types
* Tables in arbitrary syntax:: Orgtbl for LaTeX and other programs
* Dynamic blocks:: Automatically filled blocks
* Special agenda views:: Customized views
* Using the property API:: Writing programs that use entry properties
+* Using the mapping API:: Mapping over all or selected entries
@end menu
address@hidden Extensions, Adding hyperlink types, Extensions and Hacking,
Extensions and Hacking
address@hidden Third-party extensions for Org
address@hidden extension, third-party
-
-There are lots of extensions that have been written by other people. Most of
-them have either been integrated into Org by now, or they can be found in the
-Org distribution, in the @file{contrib} directory. The list has gotten too
-long to cover in any detail here, but there is a seaparate manual for these
-extensions.
-
address@hidden Adding hyperlink types, Tables in arbitrary syntax, Extensions,
Extensions and Hacking
address@hidden Adding hyperlink types, Tables in arbitrary syntax, Hacking,
Hacking
@section Adding hyperlink types
@cindex hyperlinks, adding new types
@@ -8369,7 +8736,7 @@
the link description when the link is later inserted into an Org
buffer with @kbd{C-c C-l}.
address@hidden Tables in arbitrary syntax, Dynamic blocks, Adding hyperlink
types, Extensions and Hacking
address@hidden Tables in arbitrary syntax, Dynamic blocks, Adding hyperlink
types, Hacking
@section Tables and lists in arbitrary syntax
@cindex tables, in other modes
@cindex lists, in other modes
@@ -8436,7 +8803,9 @@
@table @code
@item :skip N
-Skip the first N lines of the table. Hlines do count!
+Skip the first N lines of the table. Hlines do count as separate lines for
+this parameter!
+
@item :skipcols (n1 n2 ...)
List of columns that should be skipped. If the table has a column with
calculation marks, that column is automatically discarded as well.
@@ -8482,6 +8851,7 @@
be prompted for a table name, lets say we use @samp{salesfigures}. You
will then get the following template:
address@hidden #+ORGTBL: SEND
@example
% BEGIN RECEIVE ORGTBL salesfigures
% END RECEIVE ORGTBL salesfigures
@@ -8550,7 +8920,7 @@
The address@hidden translator function @code{orgtbl-to-latex} is already part
of
Orgtbl mode. It uses a @code{tabular} environment to typeset the table
and marks horizontal lines with @code{\hline}. Furthermore, it
-interprets the following parameters:
+interprets the following parameters (see also @ref{Translator functions}):
@table @code
@item :splice nil/t
@@ -8581,15 +8951,15 @@
@cindex HTML, and Orgtbl mode
@cindex translator function
-Orgtbl mode has several translator functions built-in:
address@hidden, @code{orgtbl-to-html}, and
address@hidden Except for @address@hidden
-HTML translator uses the same code that produces tables during HTML
-export.}, these all use a generic translator, @code{orgtbl-to-generic}.
-For example, @code{orgtbl-to-latex} itself is a very short function that
-computes the column definitions for the @code{tabular} environment,
-defines a few field and line separators and then hands over to the
-generic translator. Here is the entire code:
+Orgtbl mode has several translator functions built-in: @code{orgtbl-to-csv}
+(comma-separated values), @code{orgtbl-to-tsv} (TAB-separated values)
address@hidden, @code{orgtbl-to-html}, and @code{orgtbl-to-texinfo}.
+Except for @address@hidden HTML translator uses the same
+code that produces tables during HTML export.}, these all use a generic
+translator, @code{orgtbl-to-generic}. For example, @code{orgtbl-to-latex}
+itself is a very short function that computes the column definitions for the
address@hidden environment, defines a few field and line separators and then
+hands over to the generic translator. Here is the entire code:
@lisp
@group
@@ -8692,7 +9062,7 @@
Pressing `C-c C-c' on @code{a new house} and will insert the converted
address@hidden list between the two marker lines.
address@hidden Dynamic blocks, Special agenda views, Tables in arbitrary
syntax, Extensions and Hacking
address@hidden Dynamic blocks, Special agenda views, Tables in arbitrary
syntax, Hacking
@section Dynamic blocks
@cindex dynamic blocks
@@ -8705,6 +9075,7 @@
to the block and can also specify parameters for the function producing
the content of the block.
+#+BEGIN:dynamic block
@example
#+BEGIN: myblock :parameter1 value1 :parameter2 value2 ...
@@ -8756,7 +9127,7 @@
written in a way that is does nothing in buffers that are not in
@code{org-mode}.
address@hidden Special agenda views, Using the property API, Dynamic blocks,
Extensions and Hacking
address@hidden Special agenda views, Using the property API, Dynamic blocks,
Hacking
@section Special agenda views
@cindex agenda views, user-defined
@@ -8838,7 +9209,7 @@
(org-agenda-overriding-header "Projects waiting for something: "))))
@end lisp
address@hidden Using the property API, , Special agenda views, Extensions and
Hacking
address@hidden Using the property API, Using the mapping API, Special agenda
views, Hacking
@section Using the property API
@cindex API, for properties
@cindex properties, API
@@ -8896,7 +9267,105 @@
values and check if VALUE is in this list.
@end defun
address@hidden History and Acknowledgments, Main Index, Extensions and Hacking,
Top
address@hidden Using the mapping API, , Using the property API, Hacking
address@hidden Using the mapping API
address@hidden API, for mapping
address@hidden mapping entries, API
+
+Org has sophisticated mapping capabilities to find all entries satisfying
+certain criteria. Internally, this functionality is used to produce agenda
+views, but there is also an API that can be used to execute arbitrary
+functions for each or selected entries. The main entry point for this API
+is:
+
address@hidden org-map-entries func &optional match scope &rest skip
+Call FUNC at each headline selected by MATCH in SCOPE.
+
+FUNC is a function or a lisp form. The function will be called without
+arguments, with the cursor positioned at the beginning of the headline.
+The return values of all calls to the function will be collected and
+returned as a list.
+
+MATCH is a tags/property/todo match as it is used in the agenda tags view.
+Only headlines that are matched by this query will be considered during
+the iteration. When MATCH is nil or t, all headlines will be
+visited by the iteration.
+
+SCOPE determines the scope of this command. It can be any of:
+
address@hidden
+nil @r{the current buffer, respecting the restriction if any}
+tree @r{the subtree started with the entry at point}
+file @r{the current buffer, without restriction}
+file-with-archives
+ @r{the current buffer, and any archives associated with it}
+agenda @r{all agenda files}
+agenda-with-archives
+ @r{all agenda files with any archive files associated with them}
+(file1 file2 ...)
+ @r{if this is a list, all files in the list will be scanned}
address@hidden example
+
+The remaining args are treated as settings for the skipping facilities of
+the scanner. The following items can be given here:
+
address@hidden
+archive @r{skip trees with the archive tag}
+comment @r{skip trees with the COMMENT keyword}
+function or Lisp form
+ @r{will be used as value for @code{org-agenda-skip-function},}
+ @r{so whenever the the function returns t, FUNC}
+ @r{will not be called for that entry and search will}
+ @r{continue from the point where the function leaves it}
address@hidden example
address@hidden defun
+
+The function given to that mapping routine can really do anything you like.
+It can uce the property API (@pxref{Using the property API}) to gather more
+information about the entry, or in order to change metadate in the entry.
+Here are a couple of functions that might be handy:
+
address@hidden org-todo &optional arg
+Change the TODO state of the entry, see the docstring of the functions for
+the many possible values for the argument ARG.
address@hidden defun
+
address@hidden org-priority &optional action
+Change the priority of the entry, see the docstring of this function for the
+possible values for ACTION.
address@hidden defun
+
address@hidden org-toggle-tag tag &optional onoff
+Toggle the tag TAG in the current entry. Setting ONOFF to either @code{on}
+or @code{off} will not toggle tag, but ensure that it is either on or off.
address@hidden defun
+
address@hidden org-promote
+Promote the current entry.
address@hidden defun
+
address@hidden org-demote
+Demote the current entry.
address@hidden defun
+
+Here is a simple example that will turn all entries in the current file with
+a tag @code{TOMORROW} into TODO entries with the keyword @code{UPCOMING}.
+Entries in comment trees and in archive trees will be ignored.
+
address@hidden
+(org-map-entries
+ '(org-todo "UPCOMING")
+ "+TOMORROW" 'file 'archive 'comment)
address@hidden lisp
+
+The following example counts the number of entries with TODO keyword
address@hidden, in all agenda files.
+
address@hidden
+(length (org-map-entries t "/+WAITING" nil 'agenda))
address@hidden lisp
+
address@hidden History and Acknowledgments, Main Index, Hacking, Top
@appendix History and Acknowledgments
@cindex acknowledgments
@cindex history
@@ -8940,6 +9409,9 @@
@item
@i{Thomas Baumann} wrote @file{org-bbdb.el} and @file{org-mhe.el}.
@item
address@hidden Bataillon} created the great unicorn logo that we use on the
+Org-mode website.
address@hidden
@i{Alex Bochannek} provided a patch for rounding time stamps.
@item
@i{Charles Cave}'s suggestion sparked the implementation of templates
@@ -9039,15 +9511,16 @@
@i{Frank Ruell} solved the mystery of the @code{keymapp nil} bug, a
conflict with @file{allout.el}.
@item
address@hidden Riedy} sent a patch to fix a bug with export of TODO keywords.
address@hidden Riedy} generalized the send-receive mechanism for orgtbl tables
with
+extensive patches.
@item
address@hidden Rooke} created the Org reference card and provided lots
-of feedback.
address@hidden Rooke} created the Org reference card, provided lots
+of feedback, developed and applied standards to the Org documentation.
@item
@i{Christian Schlauer} proposed angular brackets around links, among
other things.
@item
-Linking to VM/BBDB/Gnus was inspired by @i{Tom Shannon}'s
+Linking to VM/BBDB/Gnus was first inspired by @i{Tom Shannon}'s
@file{organizer-mode.el}.
@item
@i{Ilya Shlyakhter} proposed the Archive Sibling.
@@ -9057,8 +9530,8 @@
@item
@i{Dale Smith} proposed link abbreviations.
@item
address@hidden Spiers} asked for global linking commands and inspired the link
-extension system. support mairix.
address@hidden Spiers} asked for global linking commands, inspired the link
+extension system, added support for mairix, and proposed the mapping API.
@item
@i{David O'Toole} wrote @file{org-publish.el} and drafted the manual
chapter about publishing.
@@ -9072,12 +9545,11 @@
@i{David Wainberg} suggested archiving, and improvements to the linking
system.
@item
address@hidden Wiegley} wrote @file{emacs-wiki.el} and @file{planner.el}. The
-development of Org was fully independent, and both systems are really
-different beasts in their basic ideas and implementation details. I later
-looked at John's code, however, and learned from his implementation of (i)
-links where the link itself is hidden and only a description is shown, and
-(ii) popping up a calendar to select a date. John has also contributed a
address@hidden Wiegley} wrote @file{emacs-wiki.el}, @file{planner.el}, and
address@hidden, which have similar goals as Org. Initially the
+development of Org was fully independent because I was not aware of the
+existence of these packages. But with time I have accasionally looked
+at John's code and learned a lot from it. John has also contributed a
number of great ideas and patches directly to Org, including the file
@code{org-mac-message.el}'
@item
- [Emacs-diffs] Changes to emacs/doc/misc/org.texi,v, Glenn Morris, 2008/06/13
- [Emacs-diffs] Changes to emacs/doc/misc/org.texi,v, Glenn Morris, 2008/06/14
- [Emacs-diffs] Changes to emacs/doc/misc/org.texi,v,
Carsten Dominik <=
- [Emacs-diffs] Changes to emacs/doc/misc/org.texi,v, Glenn Morris, 2008/06/17
- [Emacs-diffs] Changes to emacs/doc/misc/org.texi,v, Stephen Eglen, 2008/06/18