emacs: doc/misc/org.texi comparison

comparison doc/misc/org.texi @ 96976:86e1b62bcc3e

New version 6.06a.

author	Carsten Dominik <dominik@science.uva.nl>
date	Thu, 24 Jul 2008 14:01:49 +0000
parents	2398ec3bc9c5
children	70c4b1cbc9e3

comparison

equal deleted inserted replaced

-:60149c696033
+:86e1b62bcc3e
 \input texinfo
 @c %**start of header
 @setfilename ../../info/org
 @settitle The Org Manual
-@set VERSION 6.05a
+@set VERSION 6.06a
-@set DATE June 2008
+@set DATE July 2008
 @dircategory Emacs
 @direntry
 * Org Mode: (org).      Outline-based notes management and organizer
 @end direntry
 @quotation
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.2 or
 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
+and with the Back-Cover Texts as in (a) below.    A copy of the
-is included in the section entitled ``GNU Free Documentation License.''
+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
 developing GNU and promoting software freedom.''
 * Agenda Views::                Collecting information into views
 * Embedded LaTeX::              LaTeX fragments and formulas
 * Exporting::                   Sharing and publishing of notes
 * Publishing::                  Create a web site of linked Org files
 * Miscellaneous::               All the rest which did not fit elsewhere
-* Extensions::
+* Extensions::                  Add-ons for Org mode
-* Hacking::
+* Hacking::                     How hack your way around
 * 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
 @detailmenu
 @cindex global key bindings
 @cindex key bindings, global
 @iftex
 @b{Important:} @i{If you use copy-and-paste to copy lisp code from the
-PDF documentation as viewed by Acrobat reader to your .emacs file, the
+PDF documentation as viewed by some PDF viewers to your .emacs file, the
 single quote character comes out incorrectly and the code will not work.
 You need to fix the single quotes by hand, or copy from Info
 documentation.}
 @end iftex
 archived subtrees are not exposed, unless you configure the option
 @code{org-sparse-tree-open-archived-trees}.
 @item
 During agenda view construction (@pxref{Agenda Views}), the content of
 archived trees is ignored unless you configure the option
-@code{org-agenda-skip-archived-trees}.
+@code{org-agenda-skip-archived-trees}, in which case these trees will always
+be included.  In the agenda you can press the @kbd{v} key to get archives
+temporarily included.
 @item
 Archived trees are not exported (@pxref{Exporting}), only the headline
 is.  Configure the details using the variable
 @code{org-export-with-archived-trees}.
 @end itemize
 @node Moving subtrees,  , ARCHIVE tag, Archiving
 @subsection Moving subtrees
 @cindex external archiving
 Once an entire project is finished, you may want to move it to a different
-location.  Org can move it to an @emph{Attic Sibling} in the same tree, to a
+location.  Org can move it to an @emph{Archive Sibling} in the same tree, to a
 different tree in the current file, or to a different file, the archive file.
 @table @kbd
 @kindex C-c C-x A
 @item C-c C-x A
-Move the current entry to the @emph{Attic Sibling}.  This is a sibling of the
+Move the current entry to the @emph{Archive Sibling}.  This is a sibling of
-entry with the heading @samp{Attic} and the tag @samp{ARCHIVE}
+the entry with the heading @samp{Archive} and the tag @samp{ARCHIVE}
 (@pxref{ARCHIVE tag}).  The entry becomes a child of that sibling and in this
 way retains a lot of its original context, including inherited tags and
 approximate position in the outline.
 @kindex C-c C-x C-s
 @item C-c C-x C-s
 argument is passed on to the converter, which uses it to determine the
 separator.
 @item C-c |
 Tables can also be imported by pasting tabular text into the Org
 buffer, selecting the pasted text with @kbd{C-x C-x} and then using the
-@kbd{C-c |} command (see above under @i{Creation and conversion}.
+@kbd{C-c |} command (see above under @i{Creation and conversion}).
 @c
 @item M-x org-table-export
 Export the table, by default as a TAB-separated file.  Useful for data
 exchange with, for example, spreadsheet or database programs.  The format
 used to export the file can be configured in the variable
 | / | <> |   < |     |   > |       < |          > |
 | # |  1 |   1 |   1 |   1 |       1 |          1 |
 | # |  2 |   4 |   8 |  16 |  1.4142 |     1.1892 |
 | # |  3 |   9 |  27 |  81 |  1.7321 |     1.3161 |
 |---+----+-----+-----+-----+---------+------------|
-#+TBLFM: $3=$2^2::$4=$2^3::$5=$2^4::$6=sqrt($2)::$7=sqrt(sqrt(($2))
+#+TBLFM: $3=$2^2::$4=$2^3::$5=$2^4::$6=sqrt($2)::$7=sqrt(sqrt(($2)))
 @end example
 It is also sufficient to just insert the column group starters after
 every vertical line you'd like to have:
 @cindex format specifier
 @cindex mode, for @file{calc}
 A formula can contain an optional mode string after a semicolon.  This
 string consists of flags to influence Calc and other modes during
 execution.  By default, Org uses the standard Calc modes (precision
-12, angular units degrees, fraction and symbolic modes off.  The display
+12, angular units degrees, fraction and symbolic modes off).  The display
 format, however, has been changed to @code{(float 5)} to keep tables
 compact.  The default settings can be configured using the variable
 @code{org-calc-default-modes}.
 @example
 the colon.  The following list shows examples for each link type.
 @example
 http://www.astro.uva.nl/~dominik          @r{on the web}
 file:/home/dominik/images/jupiter.jpg     @r{file, absolute path}
+/home/dominik/images/jupiter.jpg          @r{same as above}
 file:papers/last.pdf                      @r{file, relative path}
+./papers/last.pdf                         @r{same as above}
 news:comp.emacs                           @r{Usenet link}
-mailto:adent@@galaxy.net                  @r{Mail 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}
+vm://myself@@some.where.org/folder#id    @r{VM on remote machine}
 wl:folder                                 @r{WANDERLUST folder link}
 wl:folder#id                              @r{WANDERLUST message link}
 mhe:folder                                @r{MH-E folder link}
 mhe:folder#id                             @r{MH-E message link}
 rmail:folder                              @r{RMAIL folder link}
 to be added to the hook variables
 @code{org-create-file-search-functions} and
 @code{org-execute-file-search-functions}.  See the docstring for these
 variables for more information.  Org actually uses this mechanism
 for Bib@TeX{} database files, and you can use the corresponding code as
-an implementation example.  Search for @samp{BibTeX links} in the source
+an implementation example.  See the file @file{org-bibtex.el}.
-file.
 @node TODO Items, Tags, Hyperlinks, Top
 @chapter TODO Items
 @cindex TODO items
-Org mode does not maintain TODO lists as separate documents.  Instead,
+Org mode does not maintain TODO lists as separate documents@footnote{Of
-TODO items are an integral part of the notes file, because TODO items
+course, you can make a document that contains inly long lists of TODO items,
-usually come up while taking notes!  With Org mode, simply mark any
+but this is not required.}.  Instead, TODO items are an integral part of the
-entry in a tree as being a TODO item.  In this way, information is not
+notes file, because TODO items usually come up while taking notes!  With Org
-duplicated, and the entire context from which the TODO item emerged is
+mode, simply mark any entry in a tree as being a TODO item.  In this way,
-always present.
+information is not duplicated, and the entire context from which the TODO
+item emerged is always present.
 Of course, this technique for managing TODO items scatters them
 throughout your notes file.  Org mode compensates for this by providing
 methods to give you an overview of all the things that you have to do.
 (setq org-todo-keywords
 '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED")))
 @end lisp
 The vertical bar separates the TODO keywords (states that @emph{need
-action}) from the DONE states (which need @emph{no further action}.  If
+action}) from the DONE states (which need @emph{no further action}).  If
 you don't provide the separator bar, the last state is used as the DONE
 state.
 @cindex completion, of TODO keywords
 With this setup, the command @kbd{C-c C-t} will cycle an entry from TODO
 to FEEDBACK, then to VERIFY, and finally to DONE and DELEGATED.  You may
 support for tags.
 Every headline can contain a list of tags; they occur at the end of the
 headline.  Tags are normal words containing letters, numbers, @samp{_},
 and @samp{@@}.  Tags must be preceded and followed by a single colon,
-e.g., @samp{:WORK:}.  Several tags can be specified, as in
+e.g., @samp{:work:}.  Several tags can be specified, as in
-@samp{:work:URGENT:}.
+@samp{:work:urgent:}.
 @menu
 * Tag inheritance::             Tags use the tree structure of the outline
 * Setting tags::                How to assign tags to a headline
 * Tag searches::                Searching for combinations of tags
 To create sparse trees and special lists with selection based on properties,
 the same commands are used as for tag searches (@pxref{Tag searches}), and
 the same logic applies.  For example, here is a search string:
 @example
-+work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<2+With=@{Sarah\|Denny@}
++work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<2         \
++With=@{Sarah\|Denny@}+SCHEDULED>="<2008-10-11>"
 @end example
 @noindent
+The type of comparison will depend on how the comparison value is written:
+@itemize @minus
+@item
 If the comparison value is a plain number, a numerical comparison is done,
 and the allowed operators are @samp{<}, @samp{=}, @samp{>}, @samp{<=},
-@samp{>=}, and @samp{<>}.  If the comparison value is enclosed in double
+@samp{>=}, and @samp{<>}.
-quotes, a string comparison is done, and the same operators are allowed.  If
+@item
-the comparison value is enclosed in curly braces, a regexp match is
+If the comparison value is enclosed in double
-performed, with @samp{=} meaning that the regexp matches the property value,
+quotes, a string comparison is done, and the same operators are allowed.
-and @samp{<>} meaning that it does not match.  So the search string in the
+@item
-example finds entries tagged @samp{:work:} but not @samp{:boss:}, which also
+If the comparison value is enclosed in double quotes @emph{and} angular
-have a priority value @samp{A}, a @samp{:Coffee:} property with the value
+brackets (like @samp{DEADLINE<="<2008-12-24 18:30>"}), both values are
-@samp{unlimited}, an @samp{Effort} property that is numerically smaller than
+assumed to be date/time specifications in the standard Org way@footnote{The
-2, and a @samp{:With:} property that is matched by the regular expression
+only special values that will be recognized are @samp{"<now>"} for now, and
-@samp{Sarah\|Denny}.
+@samp{"<today"} today at 0:00 hours, i.e. without a time specification.}, and
+the comparison will be done accordingly.
+@item
+If the comparison value is enclosed
+in curly braces, a regexp match is performed, with @samp{=} meaning that the
+regexp matches the property value, and @samp{<>} meaning that it does not
+match.
+@end itemize
+So the search string in the example finds entries tagged @samp{:work:} but
+not @samp{:boss:}, which also have a priority value @samp{A}, a
+@samp{:Coffee:} property with the value @samp{unlimited}, an @samp{Effort}
+property that is numerically smaller than 2, a @samp{:With:} property that is
+matched by the regular expression @samp{Sarah\|Denny}, and that are scheduled
+on or after October 11, 2008.
 You can configure Org mode to use property inheritance during a search, but
 beware that this can slow down searches considerably.  See @ref{Property
 inheritance} for details.
 When you are finished preparing a note with @i{remember}, you have to press
 @kbd{C-c 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
 now@footnote{To avoid this query, configure the variable
 @code{org-remember-clock-out-on-exit}.}.  If you answer @kbd{n}, the clock
-will continue to run after the note is filed away.
+will continue to run after the note was 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
 ranges can be specified with two time stamps, like
 @c
 @w{@samp{<2005-05-10 Tue 20:30>--<2005-05-10 Tue 22:15>}}.
 In the headline of the entry itself, a time(range) may also appear as
-plain text (like @samp{12:45} or a @samp{8:30-1pm}.  If the agenda
+plain text (like @samp{12:45} or a @samp{8:30-1pm}).  If the agenda
 integrates the Emacs diary (@pxref{Weekly/daily agenda}), time
 specifications in diary entries are recognized as well.
 For agenda display, Org mode extracts the time and displays it in a
 standard 24 hour format as part of the prefix.  The example times in
 negative, go up that many levels.  With a @kbd{C-u} prefix, do not remove the
 previously used indirect buffer.
 @c
 @kindex l
 @item l
-Toggle Logbook mode.  In Logbook mode, entries that were marked DONE while
+Toggle Logbook mode.  In Logbook mode, entries that where marked DONE while
 logging was on (variable @code{org-log-done}) are shown in the agenda,
 as are entries that have been clocked on that day.
+@c
+@kindex v
+@item v
+Toggle Archives mode.  In archives mode, trees that are marked are also
+scanned when producing the agenda.  When you call this command with a
+@kbd{C-u} prefix argument, even all archive files are included.  To exit
+archives mode, press @kbd{v} again.
 @c
 @kindex R
 @item R
 Toggle Clockreport mode.  In clockreport mode, the daily/weekly agenda will
 always show a table with the clocked times for the timespan and file scope
 The optional second and third parameter are the markup (@samp{quote},
 @samp{example}, 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.
+processed normally.  The include line will also allow additional keyword
+parameters @code{:prefix1} and @code{:prefix} to specify prefixes for the
+first line and for each following line.  For example, to include a file as an
+item, use
+@example
+#+INCLUDE: "~/snippets/xx" :prefix1 "   + " :prefix "     "
+@end example
 @table @kbd
 @kindex C-c '
 @item C-c '
 Visit the include file at point.
 files will be translated into HTML links under the assumption that an
 HTML version also exists of the linked file.  For information related to
 linking files while publishing them to a publishing directory see
 @ref{Publishing links}.
+If you want to specify attributes for links, you can do so using a special
+syntax.  Here is an example that sets @code{alt} and @code{title} attributes
+for an inlined image:
+@example
+[[./img/a.jpg@{@{alt="This is image A" title="Image with no action"@}@}]]
+@end example
 @node Images, CSS support, Links, HTML export
 @subsection Images
 @cindex images, inline in HTML
 @cindex inlining images in HTML
 .timestamp-kwd  @r{keyword associated with a time stamp, like SCHEDULED}
 .tag            @r{tag in a headline}
 .target         @r{target for links}
 @end example
-The default style specification can be configured through the option
+Each exported files contains a compact default style that defines these
-@code{org-export-html-style}.  If you want to use a file-local style,
+classes in a basic way.  You may overwrite these settings, or add to them by
-you may use file variables, best wrapped into a COMMENT section at the
+using the variables @code{org-export-html-style} (for Org-wide settings) and
-end of the outline tree.  For example@footnote{Under Emacs 21, the
+@code{org-export-html-style-extra} (for more granular settings, like
-continuation lines for a variable value should have no @samp{#} at the
+file-local settings).  If you want to use a file-local style, you may use
-start of the line.}:
+file variables, best wrapped into a COMMENT section at the end of the outline
+tree.  For example@footnote{Under Emacs 21, the continuation lines for a
+variable value should have no @samp{#} at the start of the line.}:
 @example
 * COMMENT html style specifications
 # Local Variables:
-# org-export-html-style: "   <style type=\"text/css\">
+# org-export-html-style-extra:
-#       p @{font-weight: normal; color: gray; @}
+#  "<style>
-#       h1 @{color: black; @}
+#   p  @{font-weight: normal; color: gray; @}
+#   h1 @{color: black; @}
 #   </style>"
 # End:
 @end example
-Remember to execute @kbd{M-x normal-mode} after changing this to make
+Remember to execute @kbd{M-x normal-mode} after changing this to make the new
-the new style visible to Emacs.  This command restarts Org mode for the
+style immediately visible to Emacs.  This command restarts Org mode for the
-current buffer and forces Emacs to re-evaluate the local variables
+current buffer and forces Emacs to re-evaluate the local variables section in
-section in the buffer.
+the buffer.
 @c FIXME: More about header and footer styles
 @c FIXME: Talk about links and targets.
 @node Javascript support,  , CSS support, HTML export
 @node iCalendar export,  , XOXO export, Exporting
 @section iCalendar export
 @cindex iCalendar export
-Some people like to use Org mode for keeping track of projects, but
+Some people like to use Org mode for keeping track of projects, but still
-still prefer a standard calendar application for anniversaries and
+prefer a standard calendar application for anniversaries and appointments.
-appointments.  In this case it can be useful to have deadlines and
+In this case it can be useful to have deadlines and other time-stamped items
-other time-stamped items in Org files show up in the calendar
+in Org files show up in the calendar application.  Org mode can export
-application.  Org mode can export calendar information in the standard
+calendar information in the standard iCalendar format.  If you also want to
-iCalendar format.  If you also want to have TODO entries included in the
+have TODO entries included in the export, configure the variable
-export, configure the variable @code{org-icalendar-include-todo}.
+@code{org-icalendar-include-todo}.  iCalendar export will export plain time
+stamps as VEVENT, and TODO items as VTODO.  It will also create events from
+deadlines that are in non-TODO items.  Deadlines and scheduling dates in TODO
+items will be used to set the start and due dates for the todo
+entry@footnote{See the variables @code{org-icalendar-use-deadline} and
+@code{org-icalendar-use-scheduled}.}.
 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
 @code{:ID:} property of the entry and re-used next time you report this
 The export will honor SUMMARY, DESCRIPTION and LOCATION properties if
 the selected entries have them.  If not, the summary will be derived
 from the headline, and the description from the body (limited to
 @code{org-icalendar-include-body} characters).
-How this calendar is best read and updated, depends on the application
+How this calendar is best read and updated, that depends on the application
 you are using.  The FAQ covers this issue.
 @node Publishing, Miscellaneous, Exporting, Top
 @chapter Publishing
 @cindex publishing
 @item @code{:sub-superscript}       @tab @code{org-export-with-sub-superscripts}
 @item @code{:special-strings}       @tab @code{org-export-with-special-strings}
 @item @code{:TeX-macros}            @tab @code{org-export-with-TeX-macros}
 @item @code{:LaTeX-fragments}       @tab @code{org-export-with-LaTeX-fragments}
 @item @code{:fixed-width}           @tab @code{org-export-with-fixed-width}
-@item @code{:timestamps}           .@tab @code{org-export-with-timestamps}
+@item @code{:timestamps}            @tab @code{org-export-with-timestamps}
-@item @code{:tags}                 .@tab @code{org-export-with-tags}
+@item @code{:author-info}           @tab @code{org-export-author-info}
+@item @code{:creator-info}          @tab @code{org-export-creator-info}
+@item @code{:tags}                  @tab @code{org-export-with-tags}
 @item @code{:tables}                @tab @code{org-export-with-tables}
 @item @code{:table-auto-headline}   @tab @code{org-export-highlight-first-table-line}
 @item @code{:style}                 @tab @code{org-export-html-style}
+@item @code{:style-extra}           @tab @code{org-export-html-style-extra}
 @item @code{:convert-org-links}     @tab @code{org-export-html-link-org-files-as-html}
 @item @code{:inline-images}         @tab @code{org-export-html-inline-images}
 @item @code{:expand-quoted-html}    @tab @code{org-export-html-expand}
 @item @code{:timestamp}             @tab @code{org-export-html-with-timestamp}
 @item @code{:publishing-directory}  @tab @code{org-export-publishing-directory}
 @c Local variables:
 @c ispell-local-dictionary: "en_US-w_accents"
 @c ispell-local-pdict: "./.aspell.org.pws"
 @c fill-column: 77
 @c End:

Mercurial > emacs

comparison doc/misc/org.texi @ 96976:86e1b62bcc3e