Commit b349f79f authored by Carsten Dominik's avatar Carsten Dominik
Browse files

2008-06-17 Carsten Dominik <dominik@science.uva.nl>

	* org-colview.el (org-columns-next-allowed-value): Bug fix.

	* org-colview-xemacs.el (org-columns-next-allowed-value): Bug fix.

	* org-agenda.el (org-agenda-get-closed): Get the end time into the
	agenda prefix as well.

	* org-publish.el (org-publish-org-index): Make a properly indented
	list.

	* org.el (org-calendar-agenda-action-key): New option.
	(org-get-cursor-date): New function.
	(org-mark-entry-for-agenda-action): New command.
	(org-overriding-default-time): New variable.
	(org-read-date): Respect `org-overriding-default-time'.

	* org-remember.el (org-remember-apply-template): Respect the
	ovverriding default time.

	* org-agenda.el (org-agenda-action-marker): New variable.
	(org-agenda-action): New command.
	(org-agenda-do-action): New function.

2008-06-17  Carsten Dominik  <dominik@science.uva.nl>

	* org.el (org-schedule, org-deadline): Protect scheduled and
	deadline tasks against changes that accidently remove the
	repeater.  Also show a message with the new date when done.

2008-06-17  Carsten Dominik  <dominik@science.uva.nl>

	* org.el (org-beginning-of-line): Cater for the case when there
	are tags but no headline text.
	(org-align-tags-here): Convert to tabs only when indent-tabs-mode
	it set.

2008-06-17  Carsten Dominik  <dominik@science.uva.nl>

	* org-mhe.el (org-mhe-get-message-folder-from-index): Make sure
	the return value is nil instead of "nil" when there is no match.

	* org-exp.el (org-insert-centered): Use fill-column instead of
	80.
	(org-export-as-ascii): Use string-width to measure the width of
	the heading.

	* org.el (org-diary-to-ical-string): No longer kill buffer
	FROMBUF, this is now done by the caller.

	* org-exp.el (org-print-icalendar-entries): Move the call to
	`org-diary-to-ical-string' out of the loop, and kill the buffer
	afterwords.

	* org-remember.el (org-remember-visit-immediately): Position
	cursor after moving to the note.
	(org-remember-apply-template): Use a text property to record the
	cursor position.
	(org-remember-handler): Align tags after pasting the note.

2008-06-17  Carsten Dominik  <dominik@science.uva.nl>

	* org-bbdb.el (org-bbdb-follow-anniversary-link): New function.

	* org-agenda.el (org-agenda-open-link): If there is an
	org-bbdb-name property in the current line, jump to that bbdb
	entry.

	* org-bbdb.el (org-bbdb-anniversaries): Add the bbdb-name as a
	text property, so that the agenda knows where this entry comes
	from.

	* org-agenda.el (org-agenda-clock-in): Fixed bug in the
	interaction between clocking-in from the agenda, and  automatic
	task state switching.

	* org-macs.el (org-with-point-at): Bug fix in macro defintion.

	* org.el (org-beginning-of-line, org-end-of-line): Make sure the
	zmacs-region stays after this command in XEmacs.

2008-06-17  Carsten Dominik  <dominik@science.uva.nl>

	* org.el (org-scan-tags): Allow new values for ACTION parameter.

	* org-remember.el (org-remember-templates): Fix bug in
	customization type definition.

	* org.el (org-map-entries): New function.

2008-06-17  Carsten Dominik  <dominik@science.uva.nl>

	* org-agenda.el (org-agenda-skip-comment-trees): New option.
	(org-agenda-skip): Respect `org-agenda-skip-comment-trees'.

2008-06-17  Carsten Dominik  <dominik@science.uva.nl>

	* org-remember.el (org-jump-to-target-location): New variable.
	(org-remember-apply-template): Set
	`org-remember-apply-template' if requested by template.
	(org-remember-handler): Start an idle timer to jump to
	remember location.

	* org-exp.el (org-get-current-options): Add the FILETAGS setting.

	* org.el (org-set-regexps-and-options): Fix bug with parsing of
	file tags.
	(org-get-tags-at): Add the content of `org-file-tags'.

	* org-exp.el (org-export-handle-comments): Fix bug with several
	comment lines after each other.
	(org-number-to-roman, org-number-to-counter): New functions.
	(org-export-section-number-format): New option.

2008-06-17  Carsten Dominik  <dominik@science.uva.nl>

	* org-exp.el (org-export-protect-examples): Catch the case of a
	missing end_example line.

	* org.el (org-set-regexps-and-options): Set `org-file-properties' and
	`org-file-tags' to nil.

	* org-colview.el (org-columns-next-allowed-value): Handle next
	argument NTH to directly select a value.

	* org-colview-xemacs.el (org-columns-next-allowed-value): Handle next
	argument NTH to directly select a value.

2008-06-17  Carsten Dominik  <dominik@science.uva.nl>

	* org-agenda.el (org-agenda-scheduled-leaders): Fix docstring.

2008-06-17  Carsten Dominik  <dominik@science.uva.nl>

	* org.el (org-columns-ellipses): New option.

2008-06-17  Carsten Dominik  <dominik@science.uva.nl>

	* org-colview.el (org-columns-add-ellipses): New function.
	(org-columns-compact-links): New function.
	(org-columns-cleanup-item): Call `org-columns-compact-links'.
	(org-columns-display-here): Call `org-agenda-columns-cleanup-item'
	when in agenda.
	(org-columns-edit-value): Fixed bug with editing values from
	agenda column view.
	(org-columns-redo): Also redo the agenda itself.

2008-06-17  Carsten Dominik  <dominik@science.uva.nl>

	* org-agenda.el (org-agenda-columns-remove-prefix-from-item): New
	option.

	* org-colview.el (org-agenda-columns-cleanup-item): New function.

	* org-exp.el (org-export-ascii-preprocess): Renamed from
	`org-export-ascii-clean-string'.
	(org-export-kill-licensed-text)
	(org-export-define-heading-targets)
	(org-export-handle-invisible-targets)
	(org-export-target-internal-links)
	(org-export-remove-or-extract-drawers)
	(org-export-remove-archived-trees)
	(org-export-protect-quoted-subtrees)
	(org-export-protect-verbatim, org-export-protect-examples)
	(org-export-select-backend-specific-text)
	(org-export-mark-blockquote-and-verse)
	(org-export-remove-comment-blocks-and-subtrees)
	(org-export-handle-comments, org-export-mark-radio-links)
	(org-export-remove-special-table-lines)
	(org-export-normalize-links)
	(org-export-concatenate-multiline-links)
	(org-export-concatenate-multiline-emphasis): New functions,
	obtained from spliiting the export preprocessor.

	* org-table.el (org-table-recalculate): Improve error message if
	the row number is invalid.

2008-06-17  Carsten Dominik  <dominik@science.uva.nl>

	* org-archive.el (org-archive-save-context-info): Fix bugs in
	customization setup and docstring.

	* org-exp.el (org-export-html-style): Changed the size of in the
	<pre> element to 90%.

2008-06-17  Carsten Dominik  <dominik@science.uva.nl>

	* org.el (org-find-src-example-start): Function removed.
	(org-edit-src-find-region-and-lang): New function.

2008-06-17  Carsten Dominik  <dominik@science.uva.nl>

	* org.el (org-edit-src-exit): New function.
	(org-exit-edit-mode): New minor mode.

	* org-exp.el (org-export-preprocess-string): Fix bug with removing
	comment-like lines from protected examples.

	* org.el (org-edit-src-example, org-find-src-example-start)
	(org-protect-source-example, org-edit-special): New functions.

2008-06-17  Carsten Dominik  <dominik@science.uva.nl>

	* org-publish.el (org-publish-project-alist): Fix typo in
	docstring.
	(org-publish-project-alist): Handle :index-title property.

2008-06-17  Carsten Dominik  <dominik@science.uva.nl>

	* org-export-latex.el (org-export-as-latex): Make sure region
	bounds are correct.  Parse subtree properties relating to export.

	* org-exp.el (org-export-add-options-to-plist): New function.
	(org-infile-export-plist): Use `org-export-add-options-to-plist'.

2008-06-17  Carsten Dominik  <dominik@science.uva.nl>

	* org.el (org-default-properties): Add EXPORT_FILE_NAME and
	EXPORT_TITLE.

	* org-exp.el (org-export-get-title-from-subtree)
	(org-export-as-ascii, org-export-as-html): Make sure the original
	region-beginning and region-end are used, even after moving
	point.
	(org-export-get-title-from-subtree): Also try the EXPORT_TITLE
	property.

	* org-remember.el (org-remember-last-stored-marker): New variable.
	(org-remember-goto-last-stored): Use `org-goto-marker-or-bmk'.
	(org-remember-handler): Also use marker to remember
	last-stored position.

	* org.el (org-goto-marker-or-bmk): New function.

2008-06-17  Carsten Dominik  <dominik@science.uva.nl>

	* org.el (org-file-properties): Renamed from `org-local-properties'.
	(org-scan-tags): Take file tags into account.
	(org-tags-match-list-sublevels): Default changed to t.

	* org-exp.el (org-export-as-html): Close paragraph after a
	footnote.

	* org.el (org-update-parent-todo-statistics): New function.

	* org-exp.el (org-icalendar-store-UID): New option.
	(org-icalendar-force-UID): Option removed.
	(org-print-icalendar-entries): IMplement UIDs.

2008-06-17  Carsten Dominik  <dominik@science.uva.nl>

	* org-mhe.el (org-mhe-follow-link): Fix bug in mhe searches.

2008-06-17  Carsten Dominik  <dominik@science.uva.nl>

	* org-faces.el (org-column): Document how this face is being used
	and why sometimes the background faces shine through.

	* org-mhe.el (org-mhe-follow-link): Improve handling of searches.

	* org-publish.el (org-publish-attachment): Create publishing
	directory if it does not yet exist.

	* org-table.el (org-calc-default-modes): Change default number
	format to (float 8).

	* org.el (org-olpath-completing-read): New function.
	(org-time-clocksum-format): New option.
	(org-minutes-to-hh:mm-string): Use `org-time-clocksum-format'.

	* org-clock.el (org-clock-display, org-clock-out)
	(org-update-mode-line): Use `org-time-clocksum-format'.

	* org-colview-xemacs.el (org-columns-number-to-string): Use
	`org-time-clocksum-format'.

	* org-colview.el (org-columns-number-to-string): Use
	`org-time-clocksum-format'.

2008-06-17  Carsten Dominik  <dominik@science.uva.nl>

	* org-id.el: New file, move from contrib to core.

	* org-exp.el (org-icalendar-force-UID): New option.

2008-06-17  Carsten Dominik  <dominik@science.uva.nl>

	* org-exp.el (org-print-icalendar-entries): Make sure DTEND is
	shifted by one day if theere is a date range without an end
	time.

	* org.el (org-try-structure-completion): New function.

2008-06-17  Carsten Dominik  <dominik@science.uva.nl>

	* org.el (org-set-font-lock-defaults): Improve fontification of
	description lists.
	(org-insert-item): Handle description lists.
	(org-adaptive-fill-function): Improve auto indentation in
	description lists.

	* org-exp.el (org-export-as-html, org-export-preprocess-string):
	Implement VERSE environment.
	(org-export-preprocess-string): Implement the COMMENT
	environment.

	* org-export-latex.el (org-export-latex-preprocess): Implement
	VERSE environment.

2008-06-17  Carsten Dominik  <dominik@science.uva.nl>

	* org-jsinfo.el (org-infojs-opts-table): Add entry for FIXED_TOC
	option.

2008-06-17  Carsten Dominik  <dominik@science.uva.nl>

	* org-table.el (orgtbl-to-tsv, orgtbl-to-csv): New functions.

	* org.el (org-quote-csv-field): New functions.

	* org-table.el (org-table-export-default-format): Remove :splice
	from default format, we get the same effect by not specifying
	:tstart and :tend.
	(org-table-export): Improve setup, distinguish better between
	interactive and non-interactive use, allow specifying the format
	on the fly, better protection against wrong file names.
	(orgtbl-to-generic): Fix documentation.  Do not require :tstart
	and :tend when :splice is omitted.

2008-06-17  Carsten Dominik  <dominik@science.uva.nl>

	* org-clock.el (org-clock-select-task): Make sure the selection
	letters are 1-9 and A-Z, no special characters.

2008-06-17  Carsten Dominik  <dominik@science.uva.nl>

	* org-exp.el (org-export-htmlize): New group.
	(org-export-htmlize-output-type)
	(org-export-htmlize-css-font-prefix): New options.
	(org-export-htmlize-region-for-paste): New function.
	(org-export-htmlize-generate-css): New command.

2008-06-17  Carsten Dominik  <dominik@science.uva.nl>

	* org.el (org-set-visibility-according-to-property): New function.
	(org-ctrl-c-ctrl-c): Do not restart org-mode, just get the options
	and compute the regular expressions, and update font-lock.
	(org-property-re): Allow a dash in property names.

	* org-archive.el (org-extract-archive-file): Insert the file name
	without the path into the format, to allow the location format to
	contain a subdirectory.

	* org-agenda.el (org-agenda-post-command-hook): If point is at end
	of buffer, and the `org-agenda-type' property undefined, use the
	value from the character before.

	* org.el (org-add-planning-info): Don't let indentation for
	would-be timestamp become extra whitespace at the end of headline.

2008-06-17  Carsten Dominik  <dominik@science.uva.nl>

	* org.el (org-remove-double-quotes, org-file-contents): New
	functions.

	* org-exp.el (org-infile-export-plist): Also parse the
	contents of #+SETUPFILE files, recursively.

	* org.el (org-set-regexps-and-options): Also parse the
	contents of #+SETUPFILE files, recursively.

	* org-exp.el (org-export-handle-include-files): New function.
	(org-export-preprocess-string): Call
	`org-export-handle-include-files'.

	* org.el (org-delete-property-globally)
	(org-delete-property, org-set-property): Ignore case during
	completion.
	(org-set-property): Use `org-completing-read' instead of
	`completing-read'.

	* org.el (org-complete-expand-structure-template): New,
	experimental function.
	(org-structure-template-alist): New, experimental option.
	(org-complete): Call `org-complete-expand-structure-template'.

2008-06-17 Bastien Guerry  <bzg@altern.org>

	* org-export-latex.el (org-export-latex-preprocess): Added
	support for blockquotes.

2008-06-17  Carsten Dominik  <dominik@science.uva.nl>

	* org.el (org-read-date-analyze): Catch the case where only a
	weekday is given.

2008-06-17  Carsten Dominik  <dominik@science.uva.nl>

	* org.el (org-set-font-lock-defaults): Make the description
	tag bold.

	* org-exp.el (org-export-as-html, org-close-li): Implement
	description lists.

2008-06-17 Jason Riedy  <jason@acm.org>

	* org-table.el (*orgtbl-default-fmt*): New variable.
	(orgtbl-format-line): Use the value of *orgtbl-default-fmt*
	when there is no other fmt available.

	(orgtbl-to-generic): Allow an explicitly nil :tstart or
	:tend to suppress the appropriate string.

	(orgtbl-to-orgtbl): New function for translating to another orgtbl
	table.

2008-06-17  Carsten Dominik  <dominik@science.uva.nl>

	* org.el (org-read-date-analyze): "." as an alias for "+0" in
	read date.

	* org-clock.el (org-clock-save-markers-for-cut-and-paste):
	New function.

	* org-agenda.el (org-agenda-save-markers-for-cut-and-paste):
	New function.

2008-06-17  Carsten Dominik  <dominik@science.uva.nl>

	* org-clock.el (org-clock-find-position): Don't include notes
	into clock drawer.

	* org-archive.el (org-archive-subtree): No longer remove an
	extra line after cutting the subtree.  `org-cut-subtree' already
	takes care of this.

	* org-remember.el (org-remember-handler): Only kill the target
	buffer if it does not contain the running clock.

	* org.el (org-markers-to-move): New variable.
	(org-save-markers-in-region, org-check-and-save-marker)
	(org-reinstall-markers-in-region): New function.
	(org-move-subtree-down, org-copy-subtree): Remember relative
	marker positions before cutting.
	(org-move-subtree-down, org-paste-subtree): Restore relative
	marker positions after pasting.

	* org-remember.el (org-remember-clock-out-on-exit): New option.
	(org-remember-finalize): Clock out only if the setting in
	`org-remember-clock-out-on-exit' requires it.
	(org-remember-handler): Do the cleanup in the buffer, to make sure
	that the clock marker remains in tact.

2008-06-17  Carsten Dominik  <dominik@science.uva.nl>

	* org-clock.el (org-clock-goto): Widen buffer if necessary.
	(org-clock-in): Make sure that also tasks outside the narrowed
	region will be clocked in correctly.
	(org-clock-insert-selection-line): Widen the buffer so that we can
	find the correct task heading.

	* org.el (org-base-buffer): New function.

	* org-exp.el (org-icalendar-cleanup-string): Make sure ',"
	and ";" are escaped.
	(org-print-icalendar-entries): Also apply
	`org-icalendar-cleanup-string' to the headline, not only to the
	summary property.

2008-06-17  Carsten Dominik  <dominik@science.uva.nl>

	* org-exp.el (org-export-preprocess-hook): New hook.
	(org-export-preprocess-string): Call
	`org-export-preprocess-hook'.

	* org.el (org-font-lock-hook): New variable.
	(org-font-lock-hook): New function.
	(org-set-font-lock-defaults): Call `org-font-lock-hook'.



2008-06-17  Carsten Dominik  <dominik@science.uva.nl>

	* org.texi: Modify license to no longer include back- and front
	cover matters.
	(Using the mapping API): New section.
	(Agenda column view): New section.
	(Moving subtrees): Document archiving to the archive
	sibling.
	(Agenda commands): Document columns view in the agenda.
	(Using the property API): Document the API for
	multi-valued properties.
parent 4271b424
2008-06-17 Carsten Dominik <dominik@science.uva.nl>
* org.texi: Modify license to no longer include back- and front
cover matters.
(Using the mapping API): New section.
(Agenda column view): New section.
(Moving subtrees): Document archiving to the archive
sibling.
(Agenda commands): Document columns view in the agenda.
(Using the property API): Document the API for
multi-valued properties.
2008-06-17 Jason Riedy <jason@acm.org>
* org.texi (A LaTeX example): Note that fmt may be a one-argument
function, and efmt may be a two-argument function.
(Radio tables): Document multiple destinations.
2008-06-16 Glenn Morris <rgm@gnu.org>
* epa.texi, erc.texi, pgg.texi, remember.texi, sasl.texi, url.texi:
......
......@@ -3,8 +3,8 @@
@setfilename ../../info/org
@settitle The Org Manual
@set VERSION 6.02b
@set DATE April 2008
@set VERSION 6.05a
@set DATE June 2008
@dircategory Emacs
@direntry
......@@ -43,8 +43,8 @@ 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 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 @@ license to the document, as described in section 6 of the license.
* 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 @@ Embedded LaTeX
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 @@ LaTeX export
* 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 @@ Interaction with other packages
* 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 @@ the file's name is. See also the variable
@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
@value{MAINTAINEREMAIL}.
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 @@ buffer:
#+STARTUP: showall
@end example
@noindent
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
@code{all}.
@table @kbd
@kindex C-u C-u @key{TAB}
@item 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.
@end table
@node Motion, Structure editing, Visibility cycling, Document Structure
@section Motion
@cindex motion, between headlines
......@@ -915,6 +945,12 @@ been defined in the setup). Reverse sorting is possible as well. You can
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.
@kindex C-x n s
@item C-x n s
Narrow buffer to current subtree.
@kindex C-x n w
@item 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 @@ added.
@cindex folding, sparse trees
@cindex occur, command
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
it@footnote{See also the variables @code{org-show-hierarchy-above},
@code{org-show-following-heading}, 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 it@footnote{See also the
variables @code{org-show-hierarchy-above}, @code{org-show-following-heading},
@code{org-show-siblings}, 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 @@ commands can be accessed through a dispatcher:
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
@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.
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@footnote{depending on the option
@code{org-remove-highlights-with-change}}, 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 @@ additional structure. They also provide a way to create lists of
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 @samp{*}@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 @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
@code{org-empty-line-terminates-plain-lists}. Here is an example:
Org knows ordered lists, unordered lists, and description lists.
@itemize @bullet
@item
@emph{Unordered} list items start with @samp{-}, @samp{+}, or
@samp{*}@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
@samp{*} is supported, it may be better to not use it for plain list items.}
as bullets.
@item
@emph{Ordered} list items start with a numeral followed by either a period or
a right parenthesis, such as @samp{1.} or @samp{1)}.
@item
@emph{Description} list items are like unordered list items, but contain the
separator @samp{ :: } to separate the description @emph{term} from the
desciption.
@end 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 @@ terminate all currently open plain lists, configure the variable
- 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 @@ Org supports these lists by tuning filling and wrapping commands to
deal with them correctly@footnote{Org 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}:
@code{(require 'filladapt)}}.
@code{(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 @@ Visibility cycling (@pxref{Visibility cycling}) on the headline will
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 @@ exchange with, for example, spreadsheet or database programs. The format
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 @@ for Bib@TeX{} database files, and you can use the corresponding code as
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 @@ priority):
@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 tree@footnote{To keep subtasks out
of the global TODO list, see the
@code{org-agenda-todo-list-sublevels}.}. 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 tree@footnote{To 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:
@example
* Organize Party [33%]
** TODO Call people [1/2]
*** TODO Peter
*** DONE Sarah
** TODO Buy food
** DONE Talk to neighbor
@end example
If you would like a TODO entry to automatically change to DONE when all
chilrden are done, you can use the following setup:
@example
(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)
@end 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 @@ well. For example, in the list
@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
@code{org-use-tag-inheritance}.
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.
@example
#+FILETAGS: :Peter:Boss:Secret:
@end example
@noindent
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 well@footnote{This 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 @@ Move through the column view from field to field.
@item S-@key{left}/@key{right}
Switch to the next/previous allowed value of the field. For this, you
have to have specified allowed values for a property.
@item 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 @@ exported or printed directly. If you want to capture a column view, use
this @code{columnview} dynamic block (@pxref{Dynamic blocks}). The frame
of this block looks like this:
@cindex #+BEGIN: columnview
@example
* The column view
#+BEGIN: columnview :hlines 1 :id "label"
......@@ -3948,8 +4040,10 @@ capture, you can use 3 values:
@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}
@r{@kbd{M-x 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 @@ a single letter, you use the abbreviation of day name, the date will be
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 @@ Insert @samp{SCHEDULED} keyword along with a stamp. The insertion will
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.
@c
@kindex C-c C-x C-k
@kindex k a
@kindex k s
@item 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 @@ report as an Org mode table into the current file. When the cursor is
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.
@cindex #+BEGIN: clocktable
@example
#+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file
#+END: clocktable
......@@ -4620,7 +4726,7 @@ The @kbd{l} key may be used in the timeline (@pxref{Timeline}) and in
the agenda (@pxref{Weekly/daily agenda}) to show which tasks have been
worked on or closed during a day.
@node Effort estimates
@node Effort estimates, , Clocking work time, Dates and Times
@section Effort estimates
@cindex Effort estimates
......@@ -4655,7 +4761,7 @@ In the column next to it, any clocked time will be displayed.
If you switch to column view in the daily/weekly agenda, the effort column
will summarize the estimated work effort for each day@footnote{Please 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 @@ stored: Just call @code{org-remember} with a prefix argument. If you
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 @@ use:
@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
@code{org-default-notes-file}, the heading to
@code{org-remember-default-headline}. 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
@code{org-remember-default-headline}. 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.
@code{org-remember} 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 "* %^@{Title@}\n %i\n %a" "~/org/JOURNAL.org" "New Ideas")))
@end example
......@@ -4752,8 +4866,8 @@ from an buffer in @code{emacs-lisp-mode}. The second template will only be
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 @@ insertion of content:
@r{You may specify a default value and a completion table with}
@r{%^@{prompt|default|completion2|completion3...@}}
@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 @code{%^@{Birthday@}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 @@ insertion of content:
%(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 @@ template that will be filled with the previous context information.
@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
@code{remember}. To re-use the location found during the last call to
@code{remember}, 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
@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.
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
@kbd{C-u 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 remember@footnote{Configure the
......@@ -4898,7 +5019,9 @@ filed below the target heading as a subitem. Depending on
subitem.@* 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
@code{org-refile-use-outline-path}.
@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 @@ Toggle the ARCHIVE tag for the current headline.