diff options
author | Nicolas Goaziou <mail@nicolasgoaziou.fr> | 2019-03-19 02:20:31 +0100 |
---|---|---|
committer | Nicolas Goaziou <mail@nicolasgoaziou.fr> | 2019-03-19 02:25:01 +0100 |
commit | 1a678f184fd5887d5699d867841ca529a821b377 (patch) | |
tree | 9b5a5b2f382aa5d580e4ec565451af535a08a0f5 | |
parent | 2e92b9abb90420915d4055e34ec8e0753733705b (diff) | |
download | org-mode-1a678f184fd5887d5699d867841ca529a821b377.tar.gz |
Generate compact guide from an Org file
* doc/orgguide.texi:
* doc/doclicense.texi:
* doc/docstyle.texi: Delete files.
* doc/org-guide.org: New file.
-rw-r--r-- | doc/doclicense.texi | 505 | ||||
-rw-r--r-- | doc/docstyle.texi | 10 | ||||
-rw-r--r-- | doc/org-guide.org | 2661 | ||||
-rw-r--r-- | doc/orgguide.texi | 2699 |
4 files changed, 2661 insertions, 3214 deletions
diff --git a/doc/doclicense.texi b/doc/doclicense.texi deleted file mode 100644 index 483ecdc..0000000 --- a/doc/doclicense.texi +++ /dev/null @@ -1,505 +0,0 @@ -@c The GNU Free Documentation License. -@center Version 1.3, 3 November 2008 - -@c This file is intended to be included within another document, -@c hence no sectioning command or @node. - -@display -Copyright @copyright{} 2000, 2001, 2002, 2007, 2008, 2013, 2014, 2018 Free Software Foundation, Inc. -@uref{http://fsf.org/} - -Everyone is permitted to copy and distribute verbatim copies -of this license document, but changing it is not allowed. -@end display - -@enumerate 0 -@item -PREAMBLE - -The purpose of this License is to make a manual, textbook, or other -functional and useful document @dfn{free} in the sense of freedom: to -assure everyone the effective freedom to copy and redistribute it, -with or without modifying it, either commercially or noncommercially. -Secondarily, this License preserves for the author and publisher a way -to get credit for their work, while not being considered responsible -for modifications made by others. - -This License is a kind of ``copyleft'', which means that derivative -works of the document must themselves be free in the same sense. It -complements the GNU General Public License, which is a copyleft -license designed for free software. - -We have designed this License in order to use it for manuals for free -software, because free software needs free documentation: a free -program should come with manuals providing the same freedoms that the -software does. But this License is not limited to software manuals; -it can be used for any textual work, regardless of subject matter or -whether it is published as a printed book. We recommend this License -principally for works whose purpose is instruction or reference. - -@item -APPLICABILITY AND DEFINITIONS - -This License applies to any manual or other work, in any medium, that -contains a notice placed by the copyright holder saying it can be -distributed under the terms of this License. Such a notice grants a -world-wide, royalty-free license, unlimited in duration, to use that -work under the conditions stated herein. The ``Document'', below, -refers to any such manual or work. Any member of the public is a -licensee, and is addressed as ``you''. You accept the license if you -copy, modify or distribute the work in a way requiring permission -under copyright law. - -A ``Modified Version'' of the Document means any work containing the -Document or a portion of it, either copied verbatim, or with -modifications and/or translated into another language. - -A ``Secondary Section'' is a named appendix or a front-matter section -of the Document that deals exclusively with the relationship of the -publishers or authors of the Document to the Document's overall -subject (or to related matters) and contains nothing that could fall -directly within that overall subject. (Thus, if the Document is in -part a textbook of mathematics, a Secondary Section may not explain -any mathematics.) The relationship could be a matter of historical -connection with the subject or with related matters, or of legal, -commercial, philosophical, ethical or political position regarding -them. - -The ``Invariant Sections'' are certain Secondary Sections whose titles -are designated, as being those of Invariant Sections, in the notice -that says that the Document is released under this License. If a -section does not fit the above definition of Secondary then it is not -allowed to be designated as Invariant. The Document may contain zero -Invariant Sections. If the Document does not identify any Invariant -Sections then there are none. - -The ``Cover Texts'' are certain short passages of text that are listed, -as Front-Cover Texts or Back-Cover Texts, in the notice that says that -the Document is released under this License. A Front-Cover Text may -be at most 5 words, and a Back-Cover Text may be at most 25 words. - -A ``Transparent'' copy of the Document means a machine-readable copy, -represented in a format whose specification is available to the -general public, that is suitable for revising the document -straightforwardly with generic text editors or (for images composed of -pixels) generic paint programs or (for drawings) some widely available -drawing editor, and that is suitable for input to text formatters or -for automatic translation to a variety of formats suitable for input -to text formatters. A copy made in an otherwise Transparent file -format whose markup, or absence of markup, has been arranged to thwart -or discourage subsequent modification by readers is not Transparent. -An image format is not Transparent if used for any substantial amount -of text. A copy that is not ``Transparent'' is called ``Opaque''. - -Examples of suitable formats for Transparent copies include plain -ASCII without markup, Texinfo input format, La@TeX{} input -format, SGML or XML using a publicly available -DTD, and standard-conforming simple HTML, -PostScript or PDF designed for human modification. Examples -of transparent image formats include PNG, XCF and -JPG@. Opaque formats include proprietary formats that can be -read and edited only by proprietary word processors, SGML or -XML for which the DTD and/or processing tools are -not generally available, and the machine-generated HTML, -PostScript or PDF produced by some word processors for -output purposes only. - -The ``Title Page'' means, for a printed book, the title page itself, -plus such following pages as are needed to hold, legibly, the material -this License requires to appear in the title page. For works in -formats which do not have any title page as such, ``Title Page'' means -the text near the most prominent appearance of the work's title, -preceding the beginning of the body of the text. - -The ``publisher'' means any person or entity that distributes copies -of the Document to the public. - -A section ``Entitled XYZ'' means a named subunit of the Document whose -title either is precisely XYZ or contains XYZ in parentheses following -text that translates XYZ in another language. (Here XYZ stands for a -specific section name mentioned below, such as ``Acknowledgements'', -``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' -of such a section when you modify the Document means that it remains a -section ``Entitled XYZ'' according to this definition. - -The Document may include Warranty Disclaimers next to the notice which -states that this License applies to the Document. These Warranty -Disclaimers are considered to be included by reference in this -License, but only as regards disclaiming warranties: any other -implication that these Warranty Disclaimers may have is void and has -no effect on the meaning of this License. - -@item -VERBATIM COPYING - -You may copy and distribute the Document in any medium, either -commercially or noncommercially, provided that this License, the -copyright notices, and the license notice saying this License applies -to the Document are reproduced in all copies, and that you add no other -conditions whatsoever to those of this License. You may not use -technical measures to obstruct or control the reading or further -copying of the copies you make or distribute. However, you may accept -compensation in exchange for copies. If you distribute a large enough -number of copies you must also follow the conditions in section 3. - -You may also lend copies, under the same conditions stated above, and -you may publicly display copies. - -@item -COPYING IN QUANTITY - -If you publish printed copies (or copies in media that commonly have -printed covers) of the Document, numbering more than 100, and the -Document's license notice requires Cover Texts, you must enclose the -copies in covers that carry, clearly and legibly, all these Cover -Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on -the back cover. Both covers must also clearly and legibly identify -you as the publisher of these copies. The front cover must present -the full title with all words of the title equally prominent and -visible. You may add other material on the covers in addition. -Copying with changes limited to the covers, as long as they preserve -the title of the Document and satisfy these conditions, can be treated -as verbatim copying in other respects. - -If the required texts for either cover are too voluminous to fit -legibly, you should put the first ones listed (as many as fit -reasonably) on the actual cover, and continue the rest onto adjacent -pages. - -If you publish or distribute Opaque copies of the Document numbering -more than 100, you must either include a machine-readable Transparent -copy along with each Opaque copy, or state in or with each Opaque copy -a computer-network location from which the general network-using -public has access to download using public-standard network protocols -a complete Transparent copy of the Document, free of added material. -If you use the latter option, you must take reasonably prudent steps, -when you begin distribution of Opaque copies in quantity, to ensure -that this Transparent copy will remain thus accessible at the stated -location until at least one year after the last time you distribute an -Opaque copy (directly or through your agents or retailers) of that -edition to the public. - -It is requested, but not required, that you contact the authors of the -Document well before redistributing any large number of copies, to give -them a chance to provide you with an updated version of the Document. - -@item -MODIFICATIONS - -You may copy and distribute a Modified Version of the Document under -the conditions of sections 2 and 3 above, provided that you release -the Modified Version under precisely this License, with the Modified -Version filling the role of the Document, thus licensing distribution -and modification of the Modified Version to whoever possesses a copy -of it. In addition, you must do these things in the Modified Version: - -@enumerate A -@item -Use in the Title Page (and on the covers, if any) a title distinct -from that of the Document, and from those of previous versions -(which should, if there were any, be listed in the History section -of the Document). You may use the same title as a previous version -if the original publisher of that version gives permission. - -@item -List on the Title Page, as authors, one or more persons or entities -responsible for authorship of the modifications in the Modified -Version, together with at least five of the principal authors of the -Document (all of its principal authors, if it has fewer than five), -unless they release you from this requirement. - -@item -State on the Title page the name of the publisher of the -Modified Version, as the publisher. - -@item -Preserve all the copyright notices of the Document. - -@item -Add an appropriate copyright notice for your modifications -adjacent to the other copyright notices. - -@item -Include, immediately after the copyright notices, a license notice -giving the public permission to use the Modified Version under the -terms of this License, in the form shown in the Addendum below. - -@item -Preserve in that license notice the full lists of Invariant Sections -and required Cover Texts given in the Document's license notice. - -@item -Include an unaltered copy of this License. - -@item -Preserve the section Entitled ``History'', Preserve its Title, and add -to it an item stating at least the title, year, new authors, and -publisher of the Modified Version as given on the Title Page. If -there is no section Entitled ``History'' in the Document, create one -stating the title, year, authors, and publisher of the Document as -given on its Title Page, then add an item describing the Modified -Version as stated in the previous sentence. - -@item -Preserve the network location, if any, given in the Document for -public access to a Transparent copy of the Document, and likewise -the network locations given in the Document for previous versions -it was based on. These may be placed in the ``History'' section. -You may omit a network location for a work that was published at -least four years before the Document itself, or if the original -publisher of the version it refers to gives permission. - -@item -For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve -the Title of the section, and preserve in the section all the -substance and tone of each of the contributor acknowledgements and/or -dedications given therein. - -@item -Preserve all the Invariant Sections of the Document, -unaltered in their text and in their titles. Section numbers -or the equivalent are not considered part of the section titles. - -@item -Delete any section Entitled ``Endorsements''. Such a section -may not be included in the Modified Version. - -@item -Do not retitle any existing section to be Entitled ``Endorsements'' or -to conflict in title with any Invariant Section. - -@item -Preserve any Warranty Disclaimers. -@end enumerate - -If the Modified Version includes new front-matter sections or -appendices that qualify as Secondary Sections and contain no material -copied from the Document, you may at your option designate some or all -of these sections as invariant. To do this, add their titles to the -list of Invariant Sections in the Modified Version's license notice. -These titles must be distinct from any other section titles. - -You may add a section Entitled ``Endorsements'', provided it contains -nothing but endorsements of your Modified Version by various -parties---for example, statements of peer review or that the text has -been approved by an organization as the authoritative definition of a -standard. - -You may add a passage of up to five words as a Front-Cover Text, and a -passage of up to 25 words as a Back-Cover Text, to the end of the list -of Cover Texts in the Modified Version. Only one passage of -Front-Cover Text and one of Back-Cover Text may be added by (or -through arrangements made by) any one entity. If the Document already -includes a cover text for the same cover, previously added by you or -by arrangement made by the same entity you are acting on behalf of, -you may not add another; but you may replace the old one, on explicit -permission from the previous publisher that added the old one. - -The author(s) and publisher(s) of the Document do not by this License -give permission to use their names for publicity for or to assert or -imply endorsement of any Modified Version. - -@item -COMBINING DOCUMENTS - -You may combine the Document with other documents released under this -License, under the terms defined in section 4 above for modified -versions, provided that you include in the combination all of the -Invariant Sections of all of the original documents, unmodified, and -list them all as Invariant Sections of your combined work in its -license notice, and that you preserve all their Warranty Disclaimers. - -The combined work need only contain one copy of this License, and -multiple identical Invariant Sections may be replaced with a single -copy. If there are multiple Invariant Sections with the same name but -different contents, make the title of each such section unique by -adding at the end of it, in parentheses, the name of the original -author or publisher of that section if known, or else a unique number. -Make the same adjustment to the section titles in the list of -Invariant Sections in the license notice of the combined work. - -In the combination, you must combine any sections Entitled ``History'' -in the various original documents, forming one section Entitled -``History''; likewise combine any sections Entitled ``Acknowledgements'', -and any sections Entitled ``Dedications''. You must delete all -sections Entitled ``Endorsements.'' - -@item -COLLECTIONS OF DOCUMENTS - -You may make a collection consisting of the Document and other documents -released under this License, and replace the individual copies of this -License in the various documents with a single copy that is included in -the collection, provided that you follow the rules of this License for -verbatim copying of each of the documents in all other respects. - -You may extract a single document from such a collection, and distribute -it individually under this License, provided you insert a copy of this -License into the extracted document, and follow this License in all -other respects regarding verbatim copying of that document. - -@item -AGGREGATION WITH INDEPENDENT WORKS - -A compilation of the Document or its derivatives with other separate -and independent documents or works, in or on a volume of a storage or -distribution medium, is called an ``aggregate'' if the copyright -resulting from the compilation is not used to limit the legal rights -of the compilation's users beyond what the individual works permit. -When the Document is included in an aggregate, this License does not -apply to the other works in the aggregate which are not themselves -derivative works of the Document. - -If the Cover Text requirement of section 3 is applicable to these -copies of the Document, then if the Document is less than one half of -the entire aggregate, the Document's Cover Texts may be placed on -covers that bracket the Document within the aggregate, or the -electronic equivalent of covers if the Document is in electronic form. -Otherwise they must appear on printed covers that bracket the whole -aggregate. - -@item -TRANSLATION - -Translation is considered a kind of modification, so you may -distribute translations of the Document under the terms of section 4. -Replacing Invariant Sections with translations requires special -permission from their copyright holders, but you may include -translations of some or all Invariant Sections in addition to the -original versions of these Invariant Sections. You may include a -translation of this License, and all the license notices in the -Document, and any Warranty Disclaimers, provided that you also include -the original English version of this License and the original versions -of those notices and disclaimers. In case of a disagreement between -the translation and the original version of this License or a notice -or disclaimer, the original version will prevail. - -If a section in the Document is Entitled ``Acknowledgements'', -``Dedications'', or ``History'', the requirement (section 4) to Preserve -its Title (section 1) will typically require changing the actual -title. - -@item -TERMINATION - -You may not copy, modify, sublicense, or distribute the Document -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense, or distribute it is void, and -will automatically terminate your rights under this License. - -However, if you cease all violation of this License, then your license -from a particular copyright holder is reinstated (a) provisionally, -unless and until the copyright holder explicitly and finally -terminates your license, and (b) permanently, if the copyright holder -fails to notify you of the violation by some reasonable means prior to -60 days after the cessation. - -Moreover, your license from a particular copyright holder is -reinstated permanently if the copyright holder notifies you of the -violation by some reasonable means, this is the first time you have -received notice of violation of this License (for any work) from that -copyright holder, and you cure the violation prior to 30 days after -your receipt of the notice. - -Termination of your rights under this section does not terminate the -licenses of parties who have received copies or rights from you under -this License. If your rights have been terminated and not permanently -reinstated, receipt of a copy of some or all of the same material does -not give you any rights to use it. - -@item -FUTURE REVISIONS OF THIS LICENSE - -The Free Software Foundation may publish new, revised versions -of the GNU Free Documentation License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. See -@uref{http://www.gnu.org/copyleft/}. - -Each version of the License is given a distinguishing version number. -If the Document specifies that a particular numbered version of this -License ``or any later version'' applies to it, you have the option of -following the terms and conditions either of that specified version or -of any later version that has been published (not as a draft) by the -Free Software Foundation. If the Document does not specify a version -number of this License, you may choose any version ever published (not -as a draft) by the Free Software Foundation. If the Document -specifies that a proxy can decide which future versions of this -License can be used, that proxy's public statement of acceptance of a -version permanently authorizes you to choose that version for the -Document. - -@item -RELICENSING - -``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any -World Wide Web server that publishes copyrightable works and also -provides prominent facilities for anybody to edit those works. A -public wiki that anybody can edit is an example of such a server. A -``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the -site means any set of copyrightable works thus published on the MMC -site. - -``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0 -license published by Creative Commons Corporation, a not-for-profit -corporation with a principal place of business in San Francisco, -California, as well as future copyleft versions of that license -published by that same organization. - -``Incorporate'' means to publish or republish a Document, in whole or -in part, as part of another Document. - -An MMC is ``eligible for relicensing'' if it is licensed under this -License, and if all works that were first published under this License -somewhere other than this MMC, and subsequently incorporated in whole -or in part into the MMC, (1) had no cover texts or invariant sections, -and (2) were thus incorporated prior to November 1, 2008. - -The operator of an MMC Site may republish an MMC contained in the site -under CC-BY-SA on the same site at any time before August 1, 2009, -provided the MMC is eligible for relicensing. - -@end enumerate - -@page -@heading ADDENDUM: How to use this License for your documents - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and -license notices just after the title page: - -@smallexample -@group - Copyright (C) @var{year} @var{your name}. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.3 - or any later version published by the Free Software Foundation; - with no Invariant Sections, no Front-Cover Texts, and no Back-Cover - Texts. A copy of the license is included in the section entitled ``GNU - Free Documentation License''. -@end group -@end smallexample - -If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, -replace the ``with@dots{}Texts.''@: line with this: - -@smallexample -@group - with the Invariant Sections being @var{list their titles}, with - the Front-Cover Texts being @var{list}, and with the Back-Cover Texts - being @var{list}. -@end group -@end smallexample - -If you have Invariant Sections without Cover Texts, or some other -combination of the three, merge those two alternatives to suit the -situation. - -If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, -to permit their use in free software. - -@c Local Variables: -@c ispell-local-pdict: "ispell-dict" -@c End: diff --git a/doc/docstyle.texi b/doc/docstyle.texi deleted file mode 100644 index dfd1430..0000000 --- a/doc/docstyle.texi +++ /dev/null @@ -1,10 +0,0 @@ -@c Emacs documentation style settings -@documentencoding UTF-8 -@c These two require Texinfo 5.0 or later, so we use the older -@c equivalent @set variables supported in 4.11 and hence -@ignore -@codequotebacktick on -@codequoteundirected on -@end ignore -@set txicodequoteundirected -@set txicodequotebacktick diff --git a/doc/org-guide.org b/doc/org-guide.org new file mode 100644 index 0000000..b08b873 --- /dev/null +++ b/doc/org-guide.org @@ -0,0 +1,2661 @@ +#+title: Org Mode Compact Guide +#+subtitle: Release {{{version}}} +#+author: The Org Mode Developers +#+language: en + +#+texinfo: @insertcopying + +* Copying +:PROPERTIES: +:copying: t +:END: + +Copyright \copy 2004--2019 Free Software Foundation, Inc. + +#+begin_quote +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 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 full Org manual, which is distributed together with this +compact guide. + +(a) The FSF's Back-Cover Text is: "You have the freedom to copy and +modify this GNU manual." +#+end_quote + +* Introduction +:PROPERTIES: +:DESCRIPTION: Welcome! +:END: + +Org is a mode for keeping notes, maintaining TODO lists, and doing +project planning with a fast and effective plain-text system. It is +also an authoring and publishing system, and it supports working with +source code for literal programming and reproducible research. + +This document is a much compressed derivative of the [[info:org][comprehensive Org +mode manual]]. It contains all basic features and commands, along with +important hints for customization. It is intended for beginners who +would shy back from a 200 pages manual because of sheer size. + +** Installation +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +#+attr_texinfo: :tag Important +#+begin_quote +If you are using a version of Org that is part of the Emacs +distribution, please skip this section and go directly to [[*Activation]]. +#+end_quote + +If you have downloaded Org from the web, either as a distribution +=.zip= or =.tar= file, or as a Git archive, it is best to run it +directly from the distribution directory. You need to add the =lisp/= +subdirectories to the Emacs load path. To do this, add the following +line to your Emacs init file: + +: (add-to-list 'load-path "~/path/to/orgdir/lisp") +: (add-to-list 'load-path "~/path/to/orgdir/contrib/lisp" t) + +#+texinfo: @noindent +If you have been using git or a tar ball to get Org, you need to run +the following command to generate autoload information. + +: make autoloads + +** Activation +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +Add the following lines to your Emacs init file. The last four lines +define /global/ keys for some commands---please choose suitable keys +yourself. + +#+begin_src emacs-lisp +;; The following lines are always needed. Choose your own keys. +(global-set-key (kbd "C-l") 'org-store-link) +(global-set-key (kbd "C-a") 'org-agenda) +(global-set-key (kbd "C-c") 'org-capture) +(global-set-key (kbd "C-b") 'org-switchb) +#+end_src + +Files with extension =.org= will be put into Org mode automatically. + +** Feedback +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +If you find problems with Org, or if you have questions, remarks, or +ideas about it, please mail to the Org mailing list +mailto:emacs-orgmode@gnu.org. For information on how to submit bug +reports, see the main manual. + +* Document Structure +:PROPERTIES: +:DESCRIPTION: A tree works like your brain. +:END: + +Org is an outliner. Outlines allow a document to be organized in +a hierarchical structure, which, least for me, is the best +representation of notes and thoughts. An overview of this structure +is achieved by folding, i.e., hiding large parts of the document to +show only the general document structure and the parts currently being +worked on. Org greatly simplifies the use of outlines by compressing +the entire show and hide functionalities into a single command, +~org-cycle~, which is bound to the {{{kbd(TAB)}}} key. + +** Headlines +:PROPERTIES: +:DESCRIPTION: How to typeset Org tree nodes. +:END: + +Headlines define the structure of an outline tree. The headlines in +Org start with one or more stars, on the left margin[fn:1]. For +example: + +#+begin_example +,* Top level headline +,** Second level +,*** Third level + some text +,*** Third level + more text +,* Another top level headline +#+end_example + +Note that a headline named after ~org-footnote-section~, which +defaults to =Footnotes=, is considered as special. A subtree with +this headline will be silently ignored by exporting functions. + +Some people find the many stars too noisy and would prefer an outline +that has whitespace followed by a single star as headline starters. +See [[*Miscellaneous]] for a setup to realize this. + +** Visibility Cycling +:PROPERTIES: +:DESCRIPTION: Show and hide, much simplified. +:END: + +Outlines make it possible to hide parts of the text in the buffer. +Org uses just two commands, bound to {{{kbd(TAB)}}} and +{{{kbd{S-TAB)}}} to change the visibility in the buffer. + +#+attr_texinfo: :sep , +- {{{kbd(TAB)}}} :: + + /Subtree cycling/: Rotate current subtree among the states + + : ,-> FOLDED -> CHILDREN -> SUBTREE --. + : '-----------------------------------' + + When called with a prefix argument ({{{kbd(C-u TAB)}}}), or with the + Shift key, global cycling is invoked. + +- {{{kbd(S-TAB)}}}, {{{kbd(C-u TAB)}}} :: + + /Global cycling/: Rotate the entire buffer among the states + + : ,-> OVERVIEW -> CONTENTS -> SHOW ALL --. + : '--------------------------------------' + +- {{{kbd(C-u C-u C-u TAB)}}} :: + + Show all, including drawers. + +When Emacs first visits an Org file, the global state is set to +OVERVIEW, i.e., only the top level headlines are visible. This can be +configured through the variable ~org-startup-folded~, or on a per-file +basis by adding a =STARTUP= keyword to =overview=, =content=, or +=showall=, like this: + +: #+STARTUP: content + +** Motion +:PROPERTIES: +:DESCRIPTION: Jumping to other headlines. +:END: + +The following commands jump to other headlines in the buffer. + +- {{{kbd(C-c C-n)}}} :: Next heading. + +- {{{kbd(C-c C-p)}}} :: Previous heading. + +- {{{kbd(C-c C-f)}}} :: Next heading same level. + +- {{{kbd(C-c C-b)}}} :: Previous heading same level. + +- {{{kbd(C-c C-u)}}} :: Backward to higher level heading. + +** Structure Editing +:PROPERTIES: +:DESCRIPTION: Changing sequence and level of headlines. +:END: + +#+attr_texinfo: :sep , +- {{{kbd(M-RET)}}} :: + + Insert new heading with same level as current. If point is in + a plain list item, a new item is created (see [[Plain Lists]]). When + this command is used in the middle of a line, the line is split and + the rest of the line becomes the new headline[fn:2]. + +- {{{kbd(M-S-RET)}}} :: + + Insert new TODO entry with same level as current heading. + +- {{{kbd(TAB)}}} in new, empty entry :: + + In a new entry with no text yet, {{{kbd(TAB)}}} cycles through + reasonable levels. + +- {{{kbd(M-LEFT)}}}, {{{kbd(M-RIGHT)}}} :: + + Promote or demote current heading by one level. + +- {{{kbd(M-UP)}}}, {{{kbd(M-DOWN)}}} :: + + Move subtree up or down, i.e., swap with previous or next subtree of + same level. + +- {{{kbd(C-c C-w)}}} :: + + Refile entry or region to a different location. See [[*Refile and + Copy]]. + +- {{{kbd(C-x n s)}}}, {{{kbd(C-x n w)}}} :: + + Narrow buffer to current subtree and widen it again. + +When there is an active region (Transient Mark mode), promotion and +demotion work on all headlines in the region. + +** Sparse Trees +:PROPERTIES: +:DESCRIPTION: Matches embedded in context. +:END: + +An important feature of Org mode is the ability to construct /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[fn:3]. +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: + +- {{{kbd(C-c /)}}} :: + + This prompts for an extra key to select a sparse-tree creating + command. + +- {{{kbd(C-c / r)}}} :: + + Occur. Prompts for a regexp and shows a sparse tree with all + matches. Each match is also highlighted; the highlights disappear + by pressing {{{kbd(C-c C-c)}}}. + + The other sparse tree commands select headings based on TODO + keywords, tags, or properties and will be discussed later in this + manual. + +** Plain Lists +:PROPERTIES: +:DESCRIPTION: Additional structure within an entry. +:END: + +Within an entry of the outline tree, hand-formatted lists can provide +additional structure. They also provide a way to create lists of +checkboxes (see [[*Checkboxes]]). Org supports editing such lists, and +every exporter (see [[*Exporting]]) can parse and format them. + +Org knows ordered lists, unordered lists, and description lists. + +#+attr_texinfo: :indic @bullet +- /Unordered/ list items start with =-=, =+=, or =*= as bullets. + +- /Ordered/ list items start with =1.=, or =1)=. + +- /Description/ list use =::= to separate the /term/ from the + description. + +Items belonging to the same list must have the same indentation on the +first line. An item ends before the next line that is indented like +its bullet/number, or less. A list ends when all items are closed, or +before two blank lines. An example: + +#+begin_example +,* Lord of the Rings + My favorite scenes are (in this order) + 1. The attack of the Rohirrim + 2. Eowyn's fight with the witch king + + this was already my favorite scene in the book + + I really like Miranda Otto. + Important actors in this film are: + - Elijah Wood :: He plays Frodo + - Sean Astin :: He plays Sam, Frodo's friend. +#+end_example + +The following commands act on items when point is in the first line of +an item (the line with the bullet or number). + +#+attr_texinfo: :sep , +- {{{kbd(TAB)}}} :: + + Items can be folded just like headline levels. + +- {{{kbd(M-RET)}}} :: + + Insert new item at current level. With a prefix argument, force + a new heading (see [[*Structure Editing]]). + +- {{{kbd(M-S-RET)}}} :: + + Insert a new item with a checkbox (see [[*Checkboxes]]). + +- {{{kbd(M-S-UP)}}}, {{{kbd(M-S-DOWN)}}} :: + + Move the item including subitems up/down (swap with previous/next + item of same indentation). If the list is ordered, renumbering is + automatic. + +- {{{kbd(M-LEFT)}}}, {{{kbd(M-RIGHT)}}} :: + + Decrease/increase the indentation of an item, leaving children + alone. + +- {{{kbd(M-S-LEFT)}}}, {{{kbd(M-S-RIGHT)}}} :: + + Decrease/increase the indentation of the item, including subitems. + +- {{{kbd(C-c C-c)}}} :: + + If there is a checkbox (see [[*Checkboxes]]) in the item line, toggle + the state of the checkbox. Also verify bullets and indentation + consistency in the whole list. + +- {{{kbd(C-c -)}}} :: + + Cycle the entire list level through the different itemize/enumerate + bullets (=-=, =+=, =*=, =1.=, =1)=). + +* Tables +:PROPERTIES: +:DESCRIPTION: Pure magic for quick formatting. +:END: + +Org comes with a fast and intuitive table editor. Spreadsheet-like +calculations are supported in connection with the Emacs Calc package +(see [[info:calc][GNU Emacs Calculator Manual]]). + +Org makes it easy to format tables in plain ASCII. Any line with =|= +as the first non-whitespace character is considered part of a table. +=|= is also the column separator. A table might look like this: + +#+begin_example +| Name | Phone | Age | +|-------+-------+-----| +| Peter | 1234 | 17 | +| Anna | 4321 | 25 | +#+end_example + +A table is re-aligned automatically each time you press {{{kbd(TAB)}}} +or {{{kbd(RET)}}} or {{{kbd(C-c C-c)}}} inside the table. +{{{kbd(TAB)}}} also moves to the next field ({{{kbd(RET)}}} to the +next row) and creates new table rows at the end of the table or before +horizontal lines. The indentation of the table is set by the first +line. Any line starting with =|-= is considered as a horizontal +separator line and will be expanded on the next re-align to span the +whole table width. So, to create the above table, you would only type + +: |Name|Phone|Age| +: |- + +#+texinfo: @noindent +and then press {{{kbd(TAB)}}} to align the table and start filling in +fields. Even faster would be to type =|Name|Phone|Age= followed by +{{{kbd(C-c RET)}}}. + +When typing text into a field, Org treats {{{kbd(DEL)}}}, +{{{kbd(Backspace)}}}, and all character keys in a special way, so that +inserting and deleting avoids shifting other fields. Also, when +typing /immediately after point was moved into a new field with +{{{kbd(TAB)}}}, {{{kbd(S-TAB)}}} or {{{kbd(RET)}}}/, the field is +automatically made blank. + +** Creation and conversion +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +- {{{kbd(C-c |)}}} :: + + Convert the active region to table. If every line contains at least + one {{{kbd(TAB)}}} character, the function assumes that the material + is tab separated. If every line contains a comma, comma-separated + values (CSV) are assumed. If not, lines are split at whitespace + into fields. + + If there is no active region, this command creates an empty Org + table. But it is easier just to start typing, like {{{kbd(| + N a m e | P h o n e | A g e RET | - TAB)}}}. + +** Re-aligning and field motion +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +#+attr_texinfo: :sep , +- {{{kbd(C-c C-c)}}} :: + + Re-align the table without moving point. + +- {{{kbd(TAB)}}} :: + + Re-align the table, move to the next field. Creates a new row if + necessary. + +- {{{kbd(S-TAB)}}} :: + + Re-align, move to previous field. + +- {{{kbd(RET)}}} :: + + Re-align the table and move down to next row. Creates a new row if + necessary. + +- {{{kbd(S-UP)}}}, {{{kbd(S-DOWN)}}}, {{{kbd(S-LEFT)}}}, {{{kbd(S-RIGHT)}}} :: + + Move a cell up, down, left, and right by swapping with adjacent + cell. + +** Column and row editing +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +- {{{kbd(M-LEFT)}}}, {{{kbd(M-RIGHT)}}} :: + + Move the current column left/right. + +- {{{kbd(M-S-LEFT)}}} :: + + Kill the current column. + +- {{{kbd(M-S-RIGHT)}}} :: + + Insert a new column to the left of point position. + +- {{{kbd(M-UP)}}}, {{{kbd(M-DOWN)}}} :: + + Move the current row up/down. + +- {{{kbd(M-S-UP)}}} :: + + Kill the current row or horizontal line. + +- {{{kbd(M-S-DOWN)}}} :: + + Insert a new row above the current row. With a prefix argument, the + line is created below the current one. + +- {{{kbd(C-c -)}}} :: + + Insert a horizontal line below current row. With a prefix argument, + the line is created above the current line. + +- {{{kbd(C-c RET)}}} :: + + Insert a horizontal line below current row, and move the point into + the row below that line. + +- {{{kbd(C-c ^)}}} :: + + Sort the table lines in the region. The position of point indicates + the column to be used for sorting, and the range of lines is the + range between the nearest horizontal separator lines, or the entire + table. + +* Hyperlinks +:PROPERTIES: +:DESCRIPTION: Notes in context. +:END: + +Like HTML, Org provides links inside a file, external links to other +files, Usenet articles, emails, and much more. + +Org recognizes plain URIs, possibly wrapped within angle brackets, and +activate them as clickable links. The general link format, however, +looks like this: + +: [[LINK][DESCRIPTION]] + +#+texinfo: @noindent +or alternatively + +: [[LINK]] + +Once a link in the buffer is complete, with all brackets present, Org +changes the display so that =DESCRIPTION= is displayed instead of +=[[LINK][DESCRIPTION]]= and =LINK= is displayed instead of =[[LINK]]=. +To edit the invisible {{{var(LINK)}}} part, use {{{kbd(C-c C-l)}}} +with the point on the link. + +** Internal links +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +If the link does not look like a URL, it is considered to be internal +in the current file. The most important case is a link like +=[[#my-custom-id]]= which links to the entry with the =CUSTOM_ID= property +=my-custom-id=. + +Links such as =[[My Target]]= or =[[My Target][Find my target]]= lead +to a text search in the current file for the corresponding target, +which looks like =<<My Target>>=. + +** External Links +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +Org supports links to files, websites, Usenet and email messages, BBDB +database entries and links to both IRC conversations and their logs. +External links are URL-like locators. They start with a short +identifying string followed by a colon. There can be no space after +the colon. Here are some examples: + +| =http://www.astro.uva.nl/=dominik= | on the web | +| =file:/home/dominik/images/jupiter.jpg= | file, absolute path | +| =/home/dominik/images/jupiter.jpg= | same as above | +| =file:papers/last.pdf= | file, relative path | +| =./papers/last.pdf= | same as above | +| =file:projects.org= | another Org file | +| =docview:papers/last.pdf::NNN= | open in DocView mode at page {{{var(NNN)}}} | +| =id:B7423F4D-2E8A-471B-8810-C40F074717E9= | link to heading by ID | +| =news:comp.emacs= | Usenet link | +| =mailto:adent@galaxy.net= | mail link | +| =mhe:folder#id= | MH-E message link | +| =rmail:folder#id= | Rmail message link | +| =gnus:group#id= | Gnus article link | +| =bbdb:R.*Stallman= | BBDB link (with regexp) | +| =irc:/irc.com/#emacs/bob= | IRC link | +| =info:org#Hyperlinks= | Info node link | + +File links can contain additional information to make Emacs jump to +a particular location in the file when following a link. This can be +a line number or a search option after a double colon. Here are a few +examples,, together with an explanation: + +| =file:~/code/main.c::255= | Find line 255 | +| =file:~/xx.org::My Target= | Find =<<My Target>>= | +| =[[file:~/xx.org::#my-custom-id]]= | Find entry with a custom ID | + +** Handling Links +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +Org provides methods to create a link in the correct syntax, to insert +it into an Org file, and to follow the link. + +The main function is ~org-store-link~, called with {{{kbd(M-x +org-store-link)}}}. Because of its importance, we suggest to bind it +to a widely available key (see [[*Activation]]). It stores a link to the +current location. The link is stored for later insertion into an Org +buffer---see below. + +From an Org buffer, the following commands create, navigate or, more +generally, act on links. + +#+attr_texinfo: :sep , +- {{{kbd(C-c C-l)}}} :: + + Insert a link. This prompts for a link to be inserted into the + buffer. You can just type a link, or use history keys {{{kbd(UP)}}} + and {{{kbd(DOWN)}}} to access stored links. You will be prompted + for the description part of the link. + + When called with a {{{kbd(C-u)}}} prefix argument, file name + completion is used to link to a file. + +- {{{kbd(C-c C-l)}}} (with point on existing link) :: + + When point is on an existing link, {{{kbd(C-c C-l)}}} allows you to + edit the link and description parts of the link. + +- {{{kbd(C-c C-o)}}} :: + + Open link at point. + +- {{{kbd(C-c &)}}} :: + + Jump back to a recorded position. A position is recorded by the + commands following internal links, and by {{{kbd(C-c %)}}}. Using + this command several times in direct succession moves through a ring + of previously recorded positions. + +* TODO Items +:PROPERTIES: +:DESCRIPTION: Every tree branch can be a TODO item. +:END: + +Org mode does not require TODO lists to live in separate documents. +Instead, TODO items are part of a notes file, because TODO items +usually come up while taking notes! With Org mode, simply mark any +entry in a tree as being a TODO item. In this way, information is not +duplicated, and TODO items remain in the context from which they +emerged. + +Org mode provides methods to give you an overview of all the things +that you have to do, collected from many files. + +** Basic TODO Functionality +:PROPERTIES: +:DESCRIPTION: Marking and displaying TODO entries. +:ALT_TITLE: TODO Basics +:END: + +Any headline becomes a TODO item when it starts with the word =TODO=, +for example: + +: *** TODO Write letter to Sam Fortune + +The most important commands to work with TODO entries are: + +#+attr_texinfo: :sep , +- {{{kbd(C-c C-t)}}} :: + + Rotate the TODO state of the current item among + + : ,-> (unmarked) -> TODO -> DONE --. + : '--------------------------------' + + The same rotation can also be done "remotely" from the agenda buffer + with the {{{kbd(t)}}} command key (see [[*Commands in the Agenda + Buffer]]). + +- {{{kbd(S-RIGHT)}}}, {{{kbd(S-LEFT)}}} :: + + Select the following/preceding TODO state, similar to cycling. + +- {{{kbd(C-c / t)}}} :: + + View TODO items in a /sparse tree/ (see [[*Sparse Trees]]). Folds the + entire buffer, but shows all TODO items---with not-DONE state---and + the headings hierarchy above them. + +- {{{kbd(M-x org-agenda t)}}} :: + + Show the global TODO list. Collects the TODO items (with not-DONE + states) from all agenda files (see [[*Agenda Views]]) into a single + buffer. See [[*The Global TODO List]], for more information. + +- {{{kbd(S-M-RET)}}} :: + + Insert a new TODO entry below the current one. + +Changing a TODO state can also trigger tag changes. See the docstring +of the option ~org-todo-state-tags-triggers~ for details. + +** Multi-state Workflow +:PROPERTIES: +:DESCRIPTION: More than just on/off. +:END: + +You can use TODO keywords to indicate @emph{sequential} working progress +states: + +#+begin_src emacs-lisp +(setq org-todo-keywords + '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED"))) +#+end_src + +#+texinfo: @noindent +The vertical bar separates the =TODO= keywords (states that /need +action/) from the =DONE= states (which need /no further action/). If +you do not provide the separator bar, the last state is used as the +=DONE= state. With this setup, the command {{{kbd(C-c C-t)}}} cycles +an entry from =TODO= to =FEEDBACK=, then to =VERIFY=, and finally to +=DONE= and =DELEGATED=. + +Sometimes you may want to use different sets of TODO keywords in +parallel. For example, you may want to have the basic =TODO=/=DONE=, +but also a workflow for bug fixing. Your setup would then look like +this: + +#+begin_src emacs-lisp +(setq org-todo-keywords + '((sequence "TODO(t)" "|" "DONE(d)") + (sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)"))) +#+end_src + +#+texinfo: @noindent +The keywords should all be different, this helps Org mode to keep +track of which subsequence should be used for a given entry. The +example also shows how to define keys for fast access of a particular +state, by adding a letter in parenthesis after each keyword---you will +be prompted for the key after {{{kbd(C-c C-t)}}}. + +To define TODO keywords that are valid only in a single file, use the +following text anywhere in the file. + +#+begin_example +,#+TODO: TODO(t) | DONE(d) +,#+TODO: REPORT(r) BUG(b) KNOWNCAUSE(k) | FIXED(f) +,#+TODO: | CANCELED(c) +#+end_example + +After changing one of these lines, use {{{kbd(C-c C-c)}}} with the +cursor still in the line to make the changes known to Org mode. + +** Progress Logging +:PROPERTIES: +:DESCRIPTION: Dates and notes for progress. +:END: + +Org mode can automatically record a timestamp and optionally a note +when you mark a TODO item as DONE, or even each time you change the +state of a TODO item. This system is highly configurable, settings +can be on a per-keyword basis and can be localized to a file or even +a subtree. For information on how to clock working time for a task, +see [[*Clocking Work Time]]. + +*** Closing items +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +The most basic logging is to keep track of /when/ a certain TODO item +was marked as done. This can be achieved with[fn:4] + +#+begin_src emacs-lisp +(setq org-log-done 'time) +#+end_src + +#+texinfo: @noindent +Then each time you turn an entry from a TODO (not-done) state into any +of the DONE states, a line =CLOSED: [timestamp]= is inserted just +after the headline. + +If you want to record a note along with the timestamp, use[fn:5] + +#+begin_src emacs-lisp +(setq org-log-done 'note) +#+end_src + +#+texinfo: @noindent +You are then be prompted for a note, and that note is stored below the +entry with a =Closing Note= heading. + +*** Tracking TODO state changes +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +You might want to keep track of TODO state changes. You can either +record just a timestamp, or a time-stamped note for a change. These +records are inserted after the headline as an itemized list. When +taking a lot of notes, you might want to get the notes out of the way +into a drawer. Customize the variable ~org-log-into-drawer~ to get +this behavior. + +For state logging, Org mode expects configuration on a per-keyword +basis. This is achieved by adding special markers =!= (for +a timestamp) and =@= (for a note) in parentheses after each keyword. +For example: + +: #+TODO: TODO(t) WAIT(w@/!) | DONE(d!) CANCELED(c@) + +#+texinfo: @noindent +defines TODO keywords and fast access keys, and also request that +a time is recorded when the entry is set to =DONE=, and that a note is +recorded when switching to =WAIT= or =CANCELED=. The same syntax +works also when setting ~org-todo-keywords~. + +** Priorities +:PROPERTIES: +:DESCRIPTION: Some things are more important than others. +:END: + +If you use Org mode extensively, you may end up with enough TODO items +that it starts to make sense to prioritize them. Prioritizing can be +done by placing a /priority cookie/ into the headline of a TODO item, +like this + +: *** TODO [#A] Write letter to Sam Fortune + +Org mode supports three priorities: =A=, =B=, and =C=. =A= is the +highest, =B= the default if none is given. Priorities make +a difference only in the agenda. + +#+attr_texinfo: :sep ; +- {{{kbd(C-c \,)}}} :: + + Set the priority of the current headline. Pres {{{kbd(A)}}}, + {{{kbd(B)}}} or {{{kbd(C)}}} to select a priority, or {{{kbd(SPC)}}} + to remove the cookie. + +- {{{kbd(S-UP)}}} (~org-priority-up~); {{{kbd(S-DOWN)}}} (~org-priority-down~) :: + + Increase/decrease the priority of the current headline. + +** Breaking Tasks Down into Subtasks +:PROPERTIES: +:DESCRIPTION: Splitting a task into manageable pieces. +:ALT_TITLE: Breaking Down Tasks +:END: + +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. To keep an +overview of the fraction of subtasks that have already been marked +as done, insert either =[/]= or =[%]= anywhere in the headline. These +cookies are updated each time the TODO status of a child changes, or +when pressing {{{kbd(C-c C-c)}}} on the cookie. For example: + +#+begin_example +,* Organize Party [33%] +,** TODO Call people [1/2] +,*** TODO Peter +,*** DONE Sarah +,** TODO Buy food +,** DONE Talk to neighbor +#+end_example + +** Checkboxes +:PROPERTIES: +:DESCRIPTION: Tick-off lists. +:END: + +Every item in a plain list (see [[*Plain Lists]]) can be made into +a checkbox by starting it with the string =[ ]=. Checkboxes are not +included into the global TODO list, so they are often great to split +a task into a number of simple steps. + +Here is an example of a checkbox list. + +#+begin_example +,* TODO Organize party [2/4] + - [-] call people [1/2] + - [ ] Peter + - [X] Sarah + - [X] order food +#+end_example + +Checkboxes work hierarchically, so if a checkbox item has children +that are checkboxes, toggling one of the children checkboxes makes the +parent checkbox reflect if none, some, or all of the children are +checked. + +The following commands work with checkboxes: + +- {{{kbd(C-c C-c)}}} :: + + Toggle checkbox status or---with prefix argument---checkbox presence + at point. + +- {{{kbd(M-S-RET)}}} :: + + Insert a new item with a checkbox. This works only if point is + already in a plain list item (see [[*Plain Lists]]). + +* Tags +:PROPERTIES: +:DESCRIPTION: Tagging headlines and matching sets of tags. +:END: + +An excellent way to implement labels and contexts for +cross-correlating information is to assign /tags/ to headlines. Org +mode has extensive 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, =_=, +and =@=. Tags must be preceded and followed by a single colon, e.g., +=:work:=. Several tags can be specified, as in =:work:urgent:=. Tags +by default are in bold face with the same color as the headline. + +** Tag inheritance +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +Tags make use of the hierarchical structure of outline trees. If +a heading has a certain tag, all subheadings inherit the tag as well. +For example, in the list + +#+begin_example +,* Meeting with the French group :work: +,** Summary by Frank :boss:notes: +,*** TODO Prepare slides for him :action: +#+end_example + +#+texinfo: @noindent +the final heading has the tags =work=, =boss=, =notes=, and =action= +even though the final heading is not explicitly marked with those +tags. + +You can also set tags that all entries in a file should inherit just +as if these tags were defined in a hypothetical level zero that +surrounds the entire file. Use a line like this[fn:6]: + +: #+FILETAGS: :Peter:Boss:Secret: + +** Setting tags +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +Tags can simply be typed into the buffer at the end of a headline. +After a colon, {{{kbd(M-TAB)}}} offers completion on tags. There is +also a special command for inserting tags: + +- {{{kbd(C-c C-q)}}} :: + + Enter new tags for the current headline. Org mode either offers + completion or a special single-key interface for setting tags, see + below. + +- {{{kbd(C-c C-c)}}} :: + + When point is in a headline, this does the same as {{{kbd(C-c + C-q)}}}. + +Org supports tag insertion based on a /list of tags/. By default this +list is constructed dynamically, containing all tags currently used in +the buffer. You may also globally specify a hard list of tags with +the variable ~org-tag-alist~. Finally you can set the default tags +for a given file using the =TAGS= keyword, like + +: #+TAGS: @work @home @tennisclub +: #+TAGS: laptop car pc sailboat + +By default Org mode uses the standard minibuffer completion facilities +for entering tags. However, it also implements another, quicker, tag +selection method called /fast tag selection/. This allows you to +select and deselect tags with just a single key press. For this to +work well you should assign unique letters to most of your commonly +used tags. You can do this globally by configuring the variable +~org-tag-alist~ in your Emacs init file. For example, you may find +the need to tag many items in different files with =@home=. In this +case you can set something like: + +#+begin_src emacs-lisp +(setq org-tag-alist '(("@work" . ?w) ("@home" . ?h) ("laptop" . ?l))) +#+end_src + +If the tag is only relevant to the file you are working on, then you +can instead set the =TAGS= keyword as: + +: #+TAGS: @work(w) @home(h) @tennisclub(t) laptop(l) pc(p) + +** Tag groups +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +A tag can be defined as a /group tag/ for a set of other tags. The +group tag can be seen as the "broader term" for its set of tags. + +You can set group tags by using brackets and inserting a colon between +the group tag and its related tags: + +: #+TAGS: [ GTD : Control Persp ] + +#+texinfo: @noindent +or, if tags in the group should be mutually exclusive: + +: #+TAGS: { Context : @Home @Work } + +When you search for a group tag, it return matches for all members in +the group and its subgroups. In an agenda view, filtering by a group +tag displays or hide headlines tagged with at least one of the members +of the group or any of its subgroups. + +If you want to ignore group tags temporarily, toggle group tags +support with ~org-toggle-tags-groups~, bound to {{{kbd(C-c C-x q)}}}. + +** Tag searches +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +- {{{kbd(C-c / m)}}} or {{{kbd(C-c \)}}} :: + + Create a sparse tree with all headlines matching a tags search. + With a {{{kbd(C-u)}}} prefix argument, ignore headlines that are not + a TODO line. + +- {{{kbd(M-x org-agenda m)}}} :: + + Create a global list of tag matches from all agenda files. See + [[*Matching Tags and Properties]]. + +- {{{kbd(M-x org-agenda M)}}} :: + + Create a global list of tag matches from all agenda files, but check + only TODO items and force checking subitems (see the option + ~org-tags-match-list-sublevels~). + +These commands all prompt for a match string which allows basic +Boolean logic like =+boss+urgent-project1=, to find entries with tags +=boss= and =urgent=, but not =project1=, or =Kathy|Sally= to find +entries which are tagged, like =Kathy= or =Sally=. The full syntax of +the search string is rich and allows also matching against TODO +keywords, entry levels and properties. For a more detailed description +with many examples, see [[*Matching Tags and Properties]]. + +* Properties +:PROPERTIES: +:DESCRIPTION: Storing information about an entry. +:END: + +Properties are key-value pairs associated with an entry. They live in +a special drawer with the name =PROPERTIES=. Each property is +specified on a single line, with the key (surrounded by colons) first, +and the value after it: + +#+begin_example +,* CD collection +,** Classic +,*** Goldberg Variations + :PROPERTIES: + :Title: Goldberg Variations + :Composer: J.S. Bach + :Publisher: Deutsche Grammophon + :NDisks: 1 + :END: +#+end_example + +You may define the allowed values for a particular property =Xyz= by +setting a property =Xyz_ALL=. This special property is /inherited/, +so if you set it in a level 1 entry, it applies to the entire tree. +When allowed values are defined, setting the corresponding property +becomes easier and is less prone to typing errors. For the example +with the CD collection, we can pre-define publishers and the number of +disks in a box like this: + +#+begin_example +,* CD collection + :PROPERTIES: + :NDisks_ALL: 1 2 3 4 + :Publisher_ALL: "Deutsche Grammophon" Philips EMI + :END: +#+end_example + +If you want to set properties that can be inherited by any entry in +a file, use a line like: + +: #+PROPERTY: NDisks_ALL 1 2 3 4 + +The following commands help to work with properties: + +- {{{kbd(C-c C-x p)}}} :: + + Set a property. This prompts for a property name and a value. + +- {{{kbd(C-c C-c d)}}} :: + + Remove a property from the current entry. + +To create sparse trees and special lists with selection based on +properties, the same commands are used as for tag searches (see +[[*Tags]]). The syntax for the search string is described in [[*Matching +Tags and Properties]]. + +* Dates and Times +:PROPERTIES: +:DESCRIPTION: Making items useful for planning. +:END: + +To assist project planning, TODO items can be labeled with a date +and/or a time. The specially formatted string carrying the date and +time information is called a /timestamp/ in Org mode. + +** Timestamps +:PROPERTIES: +:DESCRIPTION: Assigning a time to a tree entry. +:END: + +A timestamp is a specification of a date---possibly with a time or +a range of times---in a special format, either =<2003-09-16 Tue>= or +=<2003-09-16 Tue 09:39>= or =<2003-09-16 Tue 12:00-12:30>=. +A timestamp can appear anywhere in the headline or body of an Org tree +entry. Its presence causes entries to be shown on specific dates in +the agenda (see [[*The Weekly/daily Agenda]]). We distinguish: + +- Plain timestamp; Event; Appointment :: + + A simple timestamp just assigns a date/time to an item. This is + just like writing down an appointment or event in a paper agenda. + + #+begin_example + ,* Meet Peter at the movies + <2006-11-01 Wed 19:15> + ,* Discussion on climate change + <2006-11-02 Thu 20:00-22:00> + #+end_example + +- Timestamp with repeater interval :: + + A timestamp may contain a /repeater interval/, indicating that it + applies not only on the given date, but again and again after + a certain interval of N days (d), weeks (w), months (m), or years + (y). The following shows up in the agenda every Wednesday: + + #+begin_example + ,* Pick up Sam at school + <2007-05-16 Wed 12:30 +1w> + #+end_example + +- Diary-style expression entries :: + + #+cindex: diary style timestamps + #+cindex: sexp timestamps + For more complex date specifications, Org mode supports using the + special expression diary entries implemented in the Emacs Calendar + package. For example, with optional time: + + #+begin_example + ,* 22:00-23:00 The nerd meeting on every 2nd Thursday of the month + <%%(diary-float t 4 2)> + #+end_example + +- Time/Date range :: + + Two timestamps connected by =--= denote a range. + + #+begin_example + ,** Meeting in Amsterdam + <2004-08-23 Mon>--<2004-08-26 Thu> + #+end_example + +- Inactive timestamp :: + + Just like a plain timestamp, but with square brackets instead of + angular ones. These timestamps are inactive in the sense that they + do /not/ trigger an entry to show up in the agenda. + + #+begin_example + ,* Gillian comes late for the fifth time + [2006-11-01 Wed] + #+end_example + +** Creating Timestamps +:PROPERTIES: +:DESCRIPTION: Commands that insert timestamps. +:END: + +For Org mode to recognize timestamps, they need to be in the specific +format. All commands listed below produce timestamps in the correct +format. + +#+attr_texinfo: :sep , +- {{{kbd(C-c .)}}} :: + + Prompt for a date and insert a corresponding timestamp. When point + is at an existing timestamp in the buffer, the command is used to + modify this timestamp instead of inserting a new one. When this + command is used twice in succession, a time range is inserted. With + a prefix argument, it also adds the current time. + +- {{{kbd(C-c !)}}} :: + + Like {{{kbd(C-c .)}}}, but insert an inactive timestamp that does + not cause an agenda entry. + +- {{{kbd(S-LEFT)}}}, {{{kbd(S-RIGHT)}}} :: + + Change date at point by one day. + +- {{{kbd(S-UP)}}}, {{{kbd(S-DOWN)}}} :: + + On the beginning or enclosing bracket of a timestamp, change its + type. Within a timestamp, change the item under point. Point can + be on a year, month, day, hour or minute. When the timestamp + contains a time range like =15:30-16:30=, modifying the first time + also shifts the second, shifting the time block with constant + length. To change the length, modify the second time. + + +When Org mode prompts for a date/time, it accepts any string +containing some date and/or time information, and intelligently +interprets the string, deriving defaults for unspecified information +from the current date and time. You can also select a date in the +pop-up calendar. See the manual for more information on how exactly +the date/time prompt works. + +** Deadlines and Scheduling +:PROPERTIES: +:DESCRIPTION: Planning your work. +:END: + +A timestamp may be preceded by special keywords to facilitate +planning: + +- {{{kbd(C-c C-d)}}} :: + + Insert =DEADLINE= keyword along with a time stamp, in the line + following the headline. + + Meaning: the task---most likely a TODO item, though not + necessarily---is supposed to be finished on that date. + + On the deadline date, the task is listed in the agenda. In + addition, the agenda for /today/ carries a warning about the + approaching or missed deadline, starting ~org-deadline-warning-days~ + before the due date, and continuing until the entry is marked as + done. An example: + + #+begin_example + ,*** TODO write article about the Earth for the Guide + DEADLINE: <2004-02-29 Sun> + The editor in charge is [[bbdb:Ford Prefect]] + #+end_example + +- {{{kbd(C-c C-s)}}} :: + + Insert =SCHEDULED= keyword along with a stamp, in the line following + the headline. + + Meaning: you are planning to start working on that task on the given + date[fn:7]. + + The headline is listed under the given date[fn:8]. In addition, + a reminder that the scheduled date has passed is present in the + compilation for /today/, until the entry is marked as done, i.e., + the task is automatically forwarded until completed. + + #+begin_example + ,*** TODO Call Trillian for a date on New Years Eve. + SCHEDULED: <2004-12-25 Sat> + #+end_example + +Some tasks need to be repeated again and again. Org mode helps to +organize such tasks using a so-called repeater in a =DEADLINE=, +=SCHEDULED=, or plain timestamps. In the following example: + +#+begin_example +,** TODO Pay the rent + DEADLINE: <2005-10-01 Sat +1m> +#+end_example + +#+texinfo: @noindent +the =+1m= is a repeater; the intended interpretation is that the task +has a deadline on =<2005-10-01>= and repeats itself every (one) month +starting from that time. + +** Clocking Work Time +:PROPERTIES: +:DESCRIPTION: Tracking how long you spent on a task. +:END: + +Org mode allows you to clock the time you spend on specific tasks in +a project. + +#+attr_texinfo: :sep , +- {{{kbd(C-c C-x C-i)}}} :: + + Start the clock on the current item (clock-in). This inserts the + =CLOCK= keyword together with a timestamp. When called with + a {{{kbd(C-u)}}} prefix argument, select the task from a list of + recently clocked tasks. + +- {{{kbd(C-c C-x C-o)}}} :: + + Stop the clock (clock-out). This inserts another timestamp at the + same location where the clock was last started. It also directly + computes the resulting time in inserts it after the time range as + ==>HH:MM=. + +- {{{kbd(C-c C-x C-e)}}} :: + + Update the effort estimate for the current clock task. + +- {{{kbd(C-c C-x C-q)}}} :: + + Cancel the current clock. This is useful if a clock was started by + mistake, or if you ended up working on something else. + +- {{{kbd(C-c C-x C-j)}}} :: + + Jump to the headline of the currently clocked in task. With + a {{{kbd(C-u)}}} prefix argument, select the target task from a list + of recently clocked tasks. + +The {{{kbd(l)}}} key may be used in the agenda (see [[*The Weekly/daily +Agenda]]) to show which tasks have been worked on or closed during +a day. + +* Capture, Refile, Archive +:PROPERTIES: +:DESCRIPTION: The ins and outs for projects. +:END: + +An important part of any organization system is the ability to quickly +capture new ideas and tasks, and to associate reference material with +them. Org does this using a process called /capture/. It also can +store files related to a task (/attachments/) in a special directory. +Once in the system, tasks and projects need to be moved around. +Moving completed project trees to an archive file keeps the system +compact and fast. + +** Capture +:PROPERTIES: +:DESCRIPTION: Capturing new stuff. +:END: + +Capture lets you quickly store notes with little interruption of your +work flow. You can define templates for new entries and associate +them with different targets for storing notes. + +*** Setting up capture +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +The following customization sets a default target[fn:9] file for notes. + +#+begin_src emacs-lisp +(setq org-default-notes-file (concat org-directory "/notes.org")) +#+end_src + +You may also define a global key for capturing new material (see +[[*Activation]]). + +*** Using capture +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +- {{{kbd(M-x org-capture)}}} :: + + Start a capture process, placing you into a narrowed indirect buffer + to edit. + +- {{{kbd(C-c C-c)}}} :: + + Once you have finished entering information into the capture buffer, + {{{kbd(C-c C-c)}}} returns you to the window configuration before + the capture process, so that you can resume your work without + further distraction. + +- {{{kbd(C-c C-w)}}} :: + + Finalize the capture process by refiling the note to a different + place (see [[*Refile and Copy]]). + +- {{{kbd(C-c C-k)}}} :: + + Abort the capture process and return to the previous state. + +*** Capture templates +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +You can use templates for different types of capture items, and for +different target locations. Say you would like to use one template to +create general TODO entries, and you want to put these entries under +the heading =Tasks= in your file =~/org/gtd.org=. Also, a date tree +in the file =journal.org= should capture journal entries. A possible +configuration would look like: + +#+begin_src emacs-lisp +(setq org-capture-templates + '(("t" "Todo" entry (file+headline "~/org/gtd.org" "Tasks") + "* TODO %?\n %i\n %a") + ("j" "Journal" entry (file+datetree "~/org/journal.org") + "* %?\nEntered on %U\n %i\n %a"))) +#+end_src + +If you then press {{{kbd(t)}}} from the capture menu, Org will prepare +the template for you like this: + +: * TODO +: [[file:LINK TO WHERE YOU INITIATED CAPTURE]] + +#+texinfo: @noindent +During expansion of the template, special %-escapes[fn:10] allow +dynamic insertion of content. Here is a small selection of the +possibilities, consult the manual for more. + +| =%a= | annotation, normally the link created with ~org-store-link~ | +| =%i= | initial content, the region when capture is called with {{{kbd(C-u)}}} | +| =%t=, =%T= | timestamp, date only, or date and time | +| =%u=, =%U= | like above, but inactive timestamps | +| =%?= | after completing the template, position point here | + +** Refile and Copy +:PROPERTIES: +:DESCRIPTION: Moving/copying a tree from one place to another. +:END: + +When reviewing the captured data, you may want to refile or to copy +some of the entries into a different list, for example into a project. +Cutting, finding the right location, and then pasting the note is +cumbersome. To simplify this process, you can use the following +special command: + +- {{{kbd(C-c C-w)}}} :: + + Refile the entry or region at point. This command offers possible + locations for refiling the entry and lets you select one with + completion. The item (or all items in the region) is filed below + the target heading as a 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 ~org-refile-targets~ for + details. + +- {{{kbd(C-u C-c C-w)}}} :: + + Use the refile interface to jump to a heading. + +- {{{kbd(C-u C-u C-c C-w)}}} :: + + Jump to the location where ~org-refile~ last moved a tree to. + +- {{{kbd(C-c M-w)}}} :: + + Copying works like refiling, except that the original note is not + deleted. + +** Archiving +:PROPERTIES: +:DESCRIPTION: What to do with finished products. +:END: + +When a project represented by a (sub)tree is finished, you may want to +move the tree out of the way and to stop it from contributing to the +agenda. Archiving is important to keep your working files compact and +global searches like the construction of agenda views fast. + +The most common archiving action is to move a project tree to another +file, the archive file. + +- {{{kbd(C-c C-x C-a)}}} :: + + Archive the current entry using the command specified in the + variable ~org-archive-default-command~. + +- {{{kbd(C-c C-x C-s)}}} or short {{{kbd(C-c $)}}} :: + + Archive the subtree starting at point position to the location given + by ~org-archive-location~. + +The default archive location is a file in the same directory as the +current file, with the name derived by appending =_archive= to the +current file name. You can also choose what heading to file archived +items under, with the possibility to add them to a datetree in a file. +For information and examples on how to specify the file and the +heading, see the documentation string of the variable +~org-archive-location~. + +There is also an in-buffer option for setting this variable, for +example: + +: #+ARCHIVE: %s_done:: + +* Agenda Views +:PROPERTIES: +:DESCRIPTION: Collecting information into views. +:END: + +Due to the way Org works, TODO items, time-stamped items, and tagged +headlines can be scattered throughout a file or even a number of +files. To get an overview of open action items, or of events that are +important for a particular date, this information must be collected, +sorted and displayed in an organized way. + +The extracted information is displayed in a special /agenda buffer/. +This buffer is read-only, but provides commands to visit the +corresponding locations in the original Org files, and even to edit +these files remotely. Remote editing from the agenda buffer means, +for example, that you can change the dates of deadlines and +appointments from the agenda buffer. For commands available in the +Agenda buffer, see [[*Commands in the Agenda Buffer]]. + +** Agenda Files +:PROPERTIES: +:DESCRIPTION: Files being searched for agenda information. +:END: + +The information to be shown is normally collected from all /agenda +files/, the files listed in the variable ~org-agenda-files~. + +#+attr_texinfo: :sep or +- {{{kbd(C-c [)}}} :: + + Add current file to the list of agenda files. The file is added to + the front of the list. If it was already in the list, it is moved + to the front. With a prefix argument, file is added/moved to the + end. + +- {{{kbd(C-c ])}}} :: + + Remove current file from the list of agenda files. + +- {{{kbd(C-')}}} or {{{kbd(C-\,)}}} :: + + Cycle through agenda file list, visiting one file after the other. + +** The Agenda Dispatcher +:PROPERTIES: +:DESCRIPTION: Keyboard access to agenda views. +:ALT_TITLE: Agenda Dispatcher +:END: + +The views are created through a dispatcher, accessible with {{{kbd(M-x +org-agenda)}}}, or, better, bound to a global key (see [[*Activation]]). +It displays a menu from which an additional letter is required to +execute a command. The dispatcher offers the following default +commands: + +#+attr_texinfo: :sep , +- {{{kbd(a)}}} :: + + Create the calendar-like agenda (see [[*The Weekly/daily Agenda]]). + +- {{{kbd(t)}}}, {{{kbd(T)}}} :: + + Create a list of all TODO items (see [[*The Global TODO List]]). + +- {{{kbd(m)}}}, {{{kbd(M)}}} :: + + Create a list of headlines matching a given expression (see + [[*Matching Tags and Properties]]). + +- {{{kbd(s)}}} :: + + #+kindex: s @r{(Agenda dispatcher)} + Create a list of entries selected by a boolean expression of + keywords and/or regular expressions that must or must not occur in + the entry. + +** The Weekly/daily Agenda +:PROPERTIES: +:DESCRIPTION: What is available out of the box? +:ALT_TITLE: Built-in Agenda Views +:END: + +The purpose of the weekly/daily /agenda/ is to act like a page of +a paper agenda, showing all the tasks for the current week or day. + +- {{{kbd(M-x org-agenda a)}}} :: + + Compile an agenda for the current week from a list of Org files. + The agenda shows the entries for each day. + +Org mode understands the syntax of the diary and allows you to use +diary expression entries directly in Org files: + +#+begin_example +,* Holidays + :PROPERTIES: + :CATEGORY: Holiday + :END: +%%(org-calendar-holiday) ; special function for holiday names + +,* Birthdays + :PROPERTIES: + :CATEGORY: Ann + :END: +%%(org-anniversary 1956 5 14) Arthur Dent is %d years old +%%(org-anniversary 1869 10 2) Mahatma Gandhi would be %d years old +#+end_example + +Org can interact with Emacs appointments notification facility. To +add the appointments of your agenda files, use the command +~org-agenda-to-appt~. + +** The Global TODO List +:PROPERTIES: +:DESCRIPTION: All unfinished action items. +:ALT_TITLE: Global TODO List +:END: + +The global TODO list contains all unfinished TODO items formatted and +collected into a single place. Remote editing of TODO items lets you +can change the state of a TODO entry with a single key press. Forr +commands available in the TODO list, see [[*Commands in the Agenda +Buffer]]. + +- {{{kbd(M-x org-agenda t)}}} :: + + Show the global TODO list. This collects the TODO items from all + agenda files (see [[*Agenda Views]]) into a single buffer. + +- {{{kbd(M-x org-agenda T)}}} :: + + Like the above, but allows selection of a specific TODO keyword. + +** Matching Tags and Properties +:PROPERTIES: +:DESCRIPTION: Structured information with fine-tuned search. +:END: + +If headlines in the agenda files are marked with /tags/ (see [[*Tags]]), +or have properties (see [[*Properties]]), you can select headlines based +on this metadata and collect them into an agenda buffer. The match +syntax described here also applies when creating sparse trees with +{{{kbd(C-c / m)}}}. + +- {{{kbd(M-x org-agenda m)}}} :: + + Produce a list of all headlines that match a given set of tags. The + command prompts for a selection criterion, which is a boolean logic + expression with tags, like =+work+urgent-withboss= or =work|home= + (see [[*Tags]]). If you often need a specific search, define a custom + command for it (see [[*The Agenda Dispatcher]]). + +- {{{kbd(M-x org-agenda M)}}} :: + + Like {{{kbd(m)}}}, but only select headlines that are also TODO + items. + +A search string can use Boolean operators =&= for AND and =|= for OR. +=&= binds more strongly than =|=. Parentheses are currently not +implemented. Each element in the search is either a tag, a regular +expression matching tags, or an expression like =PROPERTY OPERATOR +VALUE= with a comparison operator, accessing a property value. Each +element may be preceded by =-= to select against it, and =+= is +syntactic sugar for positive selection. The AND operator =&= is +optional when =+= or =-= is present. Here are some examples, using +only tags. + +- =+work-boss= :: + + Select headlines tagged =work=, but discard those also tagged + =boss=. + +- =work|laptop= :: + + Selects lines tagged =work= or =laptop=. + +- =work|laptop+night= :: + + Like before, but require the =laptop= lines to be tagged also + =night=. + +You may also test for properties at the same time as matching tags, +see the manual for more information. + +** Search View +:PROPERTIES: +:DESCRIPTION: Find entries by searching for text. +:END: + +This agenda view is a general text search facility for Org mode +entries. It is particularly useful to find notes. + +- {{{kbd(M-x org-agenda s)}}} (~org-search-view~) :: + + #+kindex: s @r{(Agenda dispatcher)} + #+findex: org-search-view + This is a special search that lets you select entries by matching + a substring or specific words using a boolean logic. + +For example, the search string =computer equipment= matches entries +that contain =computer equipment= as a substring. + +Search view can also search for specific keywords in the entry, using +Boolean logic. The search string =+computer ++wifi -ethernet -{8\.11[bg]}= matches note entries that contain the +keywords =computer= and =wifi=, but not the keyword =ethernet=, and +which are also not matched by the regular expression =8\.11[bg]=, +meaning to exclude both =8.11b= and =8.11g=. + +Note that in addition to the agenda files, this command also searches +the files listed in ~org-agenda-text-search-extra-files~. + +** Commands in the Agenda Buffer +:PROPERTIES: +:DESCRIPTION: Remote editing of Org trees. +:ALT_TITLE: Agenda Commands +:END: + +Entries in the agenda buffer are linked back to the Org file or diary +file where they originate. You are not allowed to edit the agenda +buffer itself, but commands are provided to show and jump to the +original entry location, and to edit the Org files "remotely" from the +agenda buffer. This is just a selection of the many commands, explore +the agenda menu and the manual for a complete list. + +*** Motion +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +- {{{kbd(n)}}} :: + + Next line (same as {{{kbd(DOWN)}}} and {{{kbd(C-n)}}}). + +- {{{kbd(p)}}} :: + + Previous line (same as {{{kbd(UP)}}} and {{{kbd(C-p)}}}). + +*** View/Go to Org file +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +- {{{kbd(SPC)}}} :: + + Display the original location of the item in another window. + With a prefix argument, make sure that drawers stay folded. + +- {{{kbd(TAB)}}} :: + + Go to the original location of the item in another window. + +- {{{kbd(RET)}}} :: + + Go to the original location of the item and delete other windows. + +*** Change display +:PROPERTIES: +:UNNUMBERED: notoc +:END: +#+attr_texinfo: :sep , +- {{{kbd(o)}}} :: + + Delete other windows. + +- {{{kbd(v d)}}} or short {{{kbd(d)}}} :: + + Switch to day view. + +- {{{kbd(v w)}}} or short {{{kbd(w)}}} :: + + Switch to week view. + +- {{{kbd(f)}}} :: + + Go forward in time to display the span following the current one. + For example, if the display covers a week, switch to the following + week. + +- {{{kbd(b)}}} :: + + Go backward in time to display earlier dates. + +- {{{kbd(.)}}} :: + + Go to today. + +- {{{kbd(j)}}} :: + + Prompt for a date and go there. + +- {{{kbd(v l)}}} or {{{kbd(v L)}}} or short {{{kbd(l)}}} :: + + Toggle Logbook mode. In Logbook mode, entries that were marked as + done while logging was on (see the variable ~org-log-done~) are + shown in the agenda, as are entries that have been clocked on that + day. When called with a {{{kbd(C-u)}}} prefix argument, show all + possible logbook entries, including state changes. + +- {{{kbd(r)}}}, {{{kbd(g)}}} :: + + Recreate the agenda buffer, for example to reflect the changes after + modification of the timestamps of items. + +- {{{kbd(s)}}} :: + + #+kindex: C-x C-s + #+findex: org-save-all-org-buffers + #+kindex: s + Save all Org buffers in the current Emacs session, and also the + locations of IDs. + +*** Remote editing +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +- {{{kbd(0--9)}}} :: + + Digit argument. + +- {{{kbd(t)}}} :: + + Change the TODO state of the item, both in the agenda and in the + original Org file. + +- {{{kbd(C-k)}}} :: + + Delete the current agenda item along with the entire subtree + belonging to it in the original Org file. + +- {{{kbd(C-c C-w)}}} :: + + Refile the entry at point. + +- {{{kbd(a)}}} :: + + Archive the subtree corresponding to the entry at point using the + default archiving command set in ~org-archive-default-command~. + +- {{{kbd($)}}} :: + + Archive the subtree corresponding to the current headline. + +- {{{kbd(C-c C-s)}}} :: + + Schedule this item. With a prefix argument, remove the + scheduling timestamp + +- {{{kbd(C-c C-d)}}} :: + + Set a deadline for this item. With a prefix argument, remove the + deadline. + +- {{{kbd(S-RIGHT)}}} :: + + Change the timestamp associated with the current line by one day + into the future. + +- {{{kbd(S-LEFT)}}} :: + + Change the timestamp associated with the current line by one day + into the past. + +- {{{kbd(I)}}} :: + + Start the clock on the current item. + +- {{{kbd(O)}}} :: + + Stop the previously started clock. + +- {{{kbd(X)}}} :: + + Cancel the currently running clock. + +- {{{kbd(J)}}} :: + + Jump to the running clock in another window. + +*** Quit and exit +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +- {{{kbd(q)}}} :: + + Quit agenda, remove the agenda buffer. + +- {{{kbd(x)}}} :: + + Exit agenda, remove the agenda buffer and all buffers loaded by + Emacs for the compilation of the agenda. + +** Custom Agenda Views +:PROPERTIES: +:DESCRIPTION: Defining special searches and views. +:END: + +The first application of custom searches is the definition of keyboard +shortcuts for frequently used searches, either creating an agenda +buffer, or a sparse tree (the latter covering of course only the +current buffer). + +Custom commands are configured in the variable +~org-agenda-custom-commands~. You can customize this variable, for +example by pressing {{{kbd(C)}}} from the agenda dispatcher (see [[*The +Agenda Dispatcher]]). You can also directly set it with Emacs Lisp in +the Emacs init file. The following example contains all valid agenda +views: + +#+begin_src emacs-lisp +(setq org-agenda-custom-commands + '(("w" todo "WAITING") + ("u" tags "+boss-urgent") + ("v" tags-todo "+boss-urgent"))) +#+end_src + +The initial string in each entry defines the keys you have to press +after the dispatcher command in order to access the command. Usually +this is just a single character. The second parameter is the search +type, followed by the string or regular expression to be used for the +matching. The example above will therefore define: + +- {{{kbd(w)}}} :: + + as a global search for TODO entries with =WAITING= as the TODO + keyword. + +- {{{kbd(u)}}} :: + + as a global tags search for headlines tagged =boss= but not + =urgent=. + +- {{{kbd(v)}}} :: + + The same search, but limiting it to headlines that are also TODO + items. + +* Markup for Rich Contents +:PROPERTIES: +:DESCRIPTION: Compose beautiful documents. +:ALT_TITLE: Markup +:END: + +Org is primarily about organizing and searching through your +plain-text notes. However, it also provides a lightweight yet robust +markup language for rich text formatting and more. Used in +conjunction with the export framework (see [[*Exporting]]), you can author +beautiful documents in Org. + +** Paragraphs +:PROPERTIES: +:DESCRIPTION: The basic unit of text. +:END: + +Paragraphs are separated by at least one empty line. If you need to +enforce a line break within a paragraph, use =\\= at the end of +a line. + +To preserve the line breaks, indentation and blank lines in a region, +but otherwise use normal formatting, you can use this construct, which +can also be used to format poetry. + +#+begin_example +,#+BEGIN_VERSE + Great clouds overhead + Tiny black birds rise and fall + Snow covers Emacs + + ---AlexSchroeder +,#+END_VERSE +#+end_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 documents like this: + +#+begin_example +,#+BEGIN_QUOTE +Everything should be made as simple as possible, +but not any simpler ---Albert Einstein +,#+END_QUOTE +#+end_example + +If you would like to center some text, do it like this: + +#+begin_example +,#+BEGIN_CENTER +Everything should be made as simple as possible, \\ +but not any simpler +,#+END_CENTER +#+end_example + +** Emphasis and Monospace +:PROPERTIES: +:DESCRIPTION: Bold, italic, etc. +:END: + +You can make words =*bold*=, =/italic/=, =_underlined_=, ==verbatim== +and =~code~=, and, if you must, =+strike-through+=. Text in the code +and verbatim string is not processed for Org specific syntax; it is +exported verbatim. + +** Embedded LaTeX +:PROPERTIES: +:DESCRIPTION: LaTeX can be freely used inside Org documents. +:END: + +For scientific notes which need to be able to contain mathematical +symbols and the occasional formula, Org mode supports embedding LaTeX +code into its files. You can directly use TeX-like syntax for special +symbols, enter formulas and entire LaTeX environments. + +#+begin_example +The radius of the sun is R_sun = 6.96 x 10^8 m. On the other hand, +the radius of Alpha Centauri is R_{Alpha Centauri} = 1.28 x R_{sun}. + +\begin{equation} % arbitrary environments, +x=\sqrt{b} % even tables, figures +\end{equation} % etc + +If $a^2=b$ and \( b=2 \), then the solution must be +either $$ a=+\sqrt{2} $$ or \[ a=-\sqrt{2} \]. +#+end_example + +** Literal examples +:PROPERTIES: +:DESCRIPTION: Source code examples with special formatting. +:END: + +You can include literal examples that should not be subjected to +markup. Such examples are typeset in monospace, so this is well +suited for source code and similar examples. + +#+begin_example +,#+BEGIN_EXAMPLE + Some example from a text file. +,#+END_EXAMPLE +#+end_example + +For simplicity when using small examples, you can also start the +example lines with a colon followed by a space. There may also be +additional whitespace before the colon: + +#+begin_example +Here is an example + : Some example from a text file. +#+end_example + +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 buffer. + +#+begin_example +,#+BEGIN_SRC emacs-lisp + (defun org-xor (a b) + "Exclusive or." + (if a (not b) b)) + ,#+END_SRC +#+end_example + +To edit the example in a special buffer supporting this language, use +{{{kbd(C-c ')}}} to both enter and leave the editing buffer. + +** Images +:PROPERTIES: +:DESCRIPTION: Display an image. +:END: + +An image is a link to an image file that does not have a description +part, for example + +: ./img/cat.jpg + +If you wish to define a caption for the image and maybe a label for +internal cross references (see [[*Hyperlinks]]), make sure that the +link is on a line by itself and precede it with =CAPTION= and =NAME= +keywords as follows: + +#+begin_example +,#+CAPTION: This is the caption for the next figure link (or table) +,#+NAME: fig:SED-HR4049 +[[./img/a.jpg]] +#+end_example + +** Creating Footnotes +:PROPERTIES: +:DESCRIPTION: Edit and read footnotes. +:END: + +A footnote is defined in a paragraph that is started by a footnote +marker in square brackets in column 0, no indentation allowed. The +footnote reference is simply the marker in square brackets, inside +text. For example: + +#+begin_example +The Org homepage[fn:1] now looks a lot better than it used to. +... +[fn:1] The link is: https://orgmode.org +#+end_example + +The following commands handle footnotes: + +- {{{kbd(C-c C-x f)}}} :: + + The footnote action command. When point is on a footnote reference, + jump to the definition. When it is at a definition, jump to the + (first) reference. Otherwise, create a new footnote. When this + command is called with a prefix argument, a menu of additional + options including renumbering is offered. + +- {{{kbd(C-c C-c)}}} :: + + Jump between definition and reference. + +* Exporting +:PROPERTIES: +:DESCRIPTION: Sharing and publishing notes. +:END: + +Org can convert and export documents to a variety of other formats +while retaining as much structure (see [[*Document Structure]]) and markup +(see [[*Markup for Rich Contents]]) as possible. + +** The Export Dispatcher +:PROPERTIES: +:DESCRIPTION: The main interface. +:END: + +The export dispatcher is the main interface for Org's exports. +A hierarchical menu presents the currently configured export formats. +Options are shown as easy toggle switches on the same screen. + +- {{{kbd(C-c C-e)}}} :: + + Invokes the export dispatcher interface. + +Org exports the entire buffer by default. If the Org buffer has an +active region, then Org exports just that region. + +** Export Settings +:PROPERTIES: +:DESCRIPTION: Common export settings. +:END: + +The exporter recognizes special lines in the buffer which provide +additional information. These lines may be put anywhere in the file: + +: #+TITLE: I'm in the Mood for Org + +Most proeminent export options include: + +| =TITLE= | the title to be shown | +| =AUTHOR= | the author (default taken from ~user-full-name~) | +| =DATE= | a date, fixed, or an Org timestamp | +| =EMAIL= | email address (default from ~user-mail-address~) | +| =LANGUAGE= | language code, e.g., =en= | + +Option keyword sets can be inserted from the export dispatcher (see +[[*The Export Dispatcher]]) using the =Insert template= command by +pressing {{{kbd(#)}}}. + +** Table of Contents +:PROPERTIES: +:DESCRIPTION: The if and where of the table of contents. +:END: + +The table of contents includes all headlines in the document. Its +depth is therefore the same as the headline levels in the file. If +you need to use a different depth, or turn it off entirely, set the +~org-export-with-toc~ variable accordingly. You can achieve the same +on a per file basis, using the following =toc= item in =OPTIONS= +keyword: + +#+begin_example +,#+OPTIONS: toc:2 (only include two levels in TOC) +,#+OPTIONS: toc:nil (no default TOC at all) +#+end_example + +Org normally inserts the table of contents directly before the first +headline of the file. + +** Include Files +:PROPERTIES: +:DESCRIPTION: Include additional files into a document. +:END: + +During export, you can include the content of another file. For +example, to include your =.emacs= file, you could use: + +: #+INCLUDE: "~/.emacs" src emacs-lisp + +#+texinfo: @noindent +The first parameter is the file name to include. The optional second +parameter specifies the block type: =example=, =export= or =src=. The +optional third parameter specifies the source code language to use for +formatting the contents. This is relevant to both =export= and =src= +block types. + +You can visit the included file with {{{kbd(C-c ')}}}. + +** Comment Lines +:PROPERTIES: +:DESCRIPTION: What will not be exported. +:END: + +Lines starting with zero or more whitespace characters followed by one +=#= and a whitespace are treated as comments and, as such, are not +exported. + +Likewise, regions surrounded by =#+BEGIN_COMMENT= ... =#+END_COMMENT= +are not exported. + +Finally, a =COMMENT= keyword at the beginning of an entry, but after +any other keyword or priority cookie, comments out the entire subtree. +The command below helps changing the comment status of a headline. + +- {{{kbd(C-c ;)}}} :: + + Toggle the =COMMENT= keyword at the beginning of an entry. + +** ASCII/UTF-8 Export +:PROPERTIES: +:DESCRIPTION: Exporting to flat files with encoding. +:END: + +ASCII export produces an output file containing only plain ASCII +characters. This is the simplest and most direct text output. It +does not contain any Org markup. UTF-8 export uses additional +characters and symbols available in this encoding standards. + +#+attr_texinfo: :sep , +- {{{kbd(C-c C-e t a)}}}, {{{kbd(C-c C-e t u)}}} :: + + Export as an ASCII file with a =.txt= extension. For =myfile.org=, + Org exports to =myfile.txt=, overwriting without warning. For + =myfile.txt=, Org exports to =myfile.txt.txt= in order to prevent + data loss. + +** HTML Export +:PROPERTIES: +:DESCRIPTION: Exporting to HTML. +:END: + +Org mode contains an HTML exporter with extensive HTML formatting +compatible with XHTML 1.0 strict standard. + +- {{{kbd(C-c C-e h h)}}} :: + + Export as HTML file with a =.html= extension. For =myfile.org=, Org + exports to =myfile.html=, overwriting without warning. {{{kbd{C-c + C-e h o)}}} exports to HTML and opens it in a web browser. + +The HTML export back-end transforms =<= and =>= to =<= and =>=. +To include raw HTML code in the Org file so the HTML export back-end +can insert that HTML code in the output, use this inline syntax: +=@@html:...@@=. For example: + +: @@html:<b>@@bold text@@html:</b>@@ + +For larger raw HTML code blocks, use these HTML export code blocks: + +#+begin_example +,#+HTML: Literal HTML code for export + +,#+BEGIN_EXPORT html + All lines between these markers are exported literally +,#+END_EXPORT +#+end_example + +** LaTeX Export +:PROPERTIES: +:DESCRIPTION: Exporting to @LaTeX{} and processing to PDF. +:END: + +The LaTeX export back-end can handle complex documents, incorporate +standard or custom LaTeX document classes, generate documents using +alternate LaTeX engines, and produce fully linked PDF files with +indexes, bibliographies, and tables of contents, destined for +interactive online viewing or high-quality print publication. + +By default, the LaTeX output uses the /article/ class. You can change +this by adding an option like =#+LATEX_CLASS: myclass= in your file. +The class must be listed in ~org-latex-classes~. + +- {{{kbd(C-c C-e l l)}}} :: + + Export to a LaTeX file with a =.tex= extension. For =myfile.org=, + Org exports to =myfile.tex=, overwriting without warning. + +- {{{kbd(C-c C-e l p)}}} :: + + Export as LaTeX file and convert it to PDF file. + +- {{{kbd(C-c C-e l o)}}} :: + + Export as LaTeX file and convert it to PDF, then open the PDF using + the default viewer. + +The LaTeX export back-end can insert any arbitrary LaTeX code, see +[[*Embedded LaTeX]]. There are three ways to embed such code in the Org +file and they all use different quoting syntax. + +Inserting in-line quoted with @ symbols: + +: Code embedded in-line @@latex:any arbitrary LaTeX code@@ in a paragraph. + +Inserting as one or more keyword lines in the Org file: + +: #+LATEX: any arbitrary LaTeX code + +Inserting as an export block in the Org file, where the back-end +exports any code between begin and end markers: + +#+begin_example +,#+BEGIN_EXPORT latex + any arbitrary LaTeX code +,#+END_EXPORT +#+end_example + +** iCalendar Export +:PROPERTIES: +:DESCRIPTION: Exporting to iCalendar. +:END: + +A large part of Org mode's interoperability success is its ability to +easily export to or import from external applications. The iCalendar +export back-end takes calendar data from Org files and exports to the +standard iCalendar format. + +- {{{kbd(C-c C-e c f)}}} :: + + Create iCalendar entries from the current Org buffer and store them + in the same directory, using a file extension =.ics=. + +- {{{kbd(C-c C-e c c)}}} :: + + Create a combined iCalendar file from Org files in + ~org-agenda-files~ and write it to + ~org-icalendar-combined-agenda-file~ file name. + +* Publishing +:PROPERTIES: +:DESCRIPTION: Create a web site of linked Org files. +:END: + +Org includes a publishing management system that allows you to +configure automatic HTML conversion of /projects/ composed of +interlinked Org files. You can also configure Org to automatically +upload your exported HTML pages and related attachments, such as +images and source code files, to a web server. + +You can also use Org to convert files into PDF, or even combine HTML +and PDF conversion so that files are available in both formats on the +server. + +For detailed instructions about setup, see the manual. Here is an +example: + +#+begin_src emacs-lisp +(setq org-publish-project-alist + '(("org" + :base-directory "~/org/" + :publishing-directory "~/public_html" + :section-numbers nil + :table-of-contents nil + :style "<link rel=\"stylesheet\" + href=\"../other/mystyle.css\" + type=\"text/css\"/>"))) +#+end_src + +- {{{kbd(C-c C-e P x)}}} :: + + Prompt for a specific project and publish all files that belong to + it. + +- {{{kbd(C-c C-e P p)}}} :: + + Publish the project containing the current file. + +- {{{kbd(C-c C-e P f)}}} :: + + Publish only the current file. + +- {{{kbd(C-c C-e P a)}}} :: + + Publish every project. + +Org uses timestamps to track when a file has changed. The above +functions normally only publish changed files. You can override this +and force publishing of all files by giving a prefix argument to any +of the commands above. + +* Working with Source Code +:PROPERTIES: +:DESCRIPTION: Export, evaluate, and tangle code blocks. +:END: + +Org mode provides a number of features for working with source code, +including editing of code blocks in their native major mode, +evaluation of code blocks, tangling of code blocks, and exporting code +blocks and their results in several formats. + +A source code block conforms to this structure: + +#+begin_example +,#+NAME: <name> +,#+BEGIN_SRC <language> <switches> <header arguments> + <body> +,#+END_SRC +#+end_example + +#+texinfo: @noindent +where: + +- =<name>= is a string used to uniquely name the code block, + +- =<language>= specifies the language of the code block, e.g., + =emacs-lisp=, =shell=, =R=, =python=, etc., + +- =<switches>= can be used to control export of the code block, + +- =<header arguments>= can be used to control many aspects of code + block behavior as demonstrated below, + +- =<body>= contains the actual source code. + +Use {{{kbd(C-c ')}}} to edit the current code block. It opens a new +major mode edit buffer containing the body of the source code block, +ready for any edits. Use {{{kbd(C-c ')}}} again to close the buffer +and return to the Org buffer. + +** Using header arguments +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +A header argument is specified with an initial colon followed by the +argument's name in lowercase. + +Header arguments can be set in several ways; Org prioritizes them in +case of overlaps or conflicts by giving local settings a higher +priority. + +- System-wide header arguments :: + + Those are specified by customizing ~org-babel-default-header-args~ + variable, or, for a specific language {{{var(LANG)}}} + ~org-babel-default-header-args:LANG~. + +- Header arguments in properties :: + + You can set them using =header-args= property (see [[*Properties]])---or + =header-args:LANG= for language {{{var(LANG)}}}. Header arguments + set through properties drawers apply at the sub-tree level on down. + +- Header arguments in code blocks :: + + Header arguments are most commonly set at the source code block + level, on the =BEGIN_SRC= line: + + #+begin_example + ,#+NAME: factorial + ,#+BEGIN_SRC haskell :results silent :exports code :var n=0 + fac 0 = 1 + fac n = n * fac (n-1) + ,#+END_SRC + #+end_example + + Code block header arguments can span multiple lines using =HEADER= + keyword on each line. + +** Evaluating code blocks +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +Use {{{kbd(C-c C-c)}}} to evaluate the current code block and insert +its results in the Org document. By default, evaluation is only +turned on for =emacs-lisp= code blocks, however support exists for +evaluating blocks in many languages. For a complete list of supported +languages see the manual. The following shows a code block and its +results. + +#+begin_example +,#+BEGIN_SRC emacs-lisp + (+ 1 2 3 4) +,#+END_SRC + +,#+RESULTS: +: 10 +#+end_example + +The following syntax is used to pass arguments to code blocks using +the =var= header argument. + +: :var NAME=ASSIGN + +#+texinfo: @noindent +{{{var(NAME)}}} is the name of the variable bound in the code block +body. {{{var(ASSIGN)}}} is a literal value, such as a string, +a number, a reference to a table, a list, a literal example, another +code block---with or without arguments---or the results of evaluating +a code block. + +** Results of evaluation +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +How Org handles results of a code block execution depends on many +header arguments working together. The primary determinant, however, +is the =results= header argument. It controls the /collection/, +/type/, /format/, and /handling/ of code block results. + +- Collection :: + + How the results should be collected from the code block. You may + choose either =output= or =value= (the default). + +- Type :: + + What result types to expect from the execution of the code block. + You may choose among =table=, =list=, =scalar=, and =file=. Org + tries to guess it if you do not provide it. + +- Format :: + + How Org processes results. Some possible values are =code=, + =drawer=, =html=, =latex=, =link=, and =raw=. + +- Handling :: + + How to insert the results once properly formatted. Allowed values + are =silent=, =replace= (the default), =append=, or =prepend=. + +Code blocks which output results to files---e.g.: graphs, diagrams and +figures---can accept a =:file FILENAME= header argument, in which case +the results are saved to the named file, and a link to the file is +inserted into the buffer. + +** Exporting code blocks +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +It is possible to export the /code/ of code blocks, the /results/ of +code block evaluation, /both/ the code and the results of code block +evaluation, or /none/. Org defaults to exporting /code/ for most +languages. + +The =exports= header argument is to specify if that part of the Org +file is exported to, say, HTML or LaTeX formats. It can be set to +either =code=, =results=, =both= or =none=. + +** Extracting source code +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +Use {{{kbd(C-c C-v t)}}} to create pure source code files by +extracting code from source blocks in the current buffer. This is +referred to as "tangling"---a term adopted from the literate +programming community. During tangling of code blocks their bodies +are expanded using ~org-babel-expand-src-block~, which can expand both +variable and "Noweb" style references. In order to tangle a code +block it must have a =tangle= header argument, see the manual for +details. + +* Miscellaneous +:PROPERTIES: +:DESCRIPTION: All the rest which did not fit elsewhere. +:END: + +** Completion +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +Org has in-buffer completions with {{{kbd(M-TAB)}}}. No minibuffer is +involved. Type one or more letters and invoke the hot key to complete +the text in-place. + +For example, this command will complete TeX symbols after =\=, TODO +keywords at the beginning of a headline, and tags after =:= in +a headline. + +** Clean view +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +Org's default outline with stars and no indents can become too +cluttered for short documents. For /book-like/ long documents, the +effect is not as noticeable. Org provides an alternate stars and +indentation scheme, as shown on the right in the following table. It +uses only one star and indents text to line with the heading: + +#+begin_example +,* Top level headline | * Top level headline +,** Second level | * Second level +,*** Third level | * Third level + some text | some text +,*** Third level | * Third level + more text | more text +,* Another top level headline | * Another top level headline +#+end_example + +This kind of view can be achieved dynamically at display time using +Org Indent mode, which prepends intangible space to each line. You +can turn on Org Indent mode for all files by customizing the variable +~org-startup-indented~, or you can turn it on for individual files +using + +: #+STARTUP: indent + +If you want the indentation to be hard space characters so that the +plain text file looks as similar as possible to the Emacs display, Org +supports you by helping to indent (with {{{kbd(TAB)}}}) text below +each headline, by hiding leading stars, and by only using levels 1, 3, +etc to get two characters indentation for each level. To get this +support in a file, use + +: #+STARTUP: hidestars odd + +* Export Setup :noexport: + + # XXX: We cannot use TODO keyword as a node starts with "TODO". +#+todo: REVIEW FIXME | DONE +#+property: header-args :eval no +#+startup: overview nologdone + +#+export_file_name: orgguide.texi + +#+texinfo_dir_category: Emacs +#+texinfo_dir_title: Org Guide: (orgguide) +#+texinfo_dir_desc: Abbreviated Org mode manual + +# Use proper quote and backtick for code sections in PDF output +# Cf. Texinfo manual 14.2 +#+texinfo_header: @set txicodequoteundirected +#+texinfo_header: @set txicodequotebacktick + +#+options: H:4 num:t toc:t author:t \n:nil ::t |:t ^:nil -:t f:t *:t <:t e:t ':t +#+options: d:nil todo:nil pri:nil tags:not-in-toc stat:nil broken-links:mark +#+select_tags: export +#+exclude_tags: noexport + +#+macro: cite @@texinfo:@cite{@@$1@@texinfo:}@@ +#+macro: var @@texinfo:@var{@@$1@@texinfo:}@@ + +# The "version" macro extracts "Version" keyword from "org.el". It +# returns major.minor version number. This is sufficient since bugfix +# releases are not expected to add features and therefore imply manual +# modifications. +#+macro: version (eval (with-current-buffer (find-file-noselect "../lisp/org.el") (org-with-point-at 1 (if (re-search-forward "Version: +\\([0-9.]+\\)" nil t) (mapconcat #'identity (cl-subseq (split-string (match-string-no-properties 1) "\\.") 0 2) ".") (error "Missing \"Version\" keyword in \"org.el\""))))) + +# The "kbd" macro turns KBD into @kbd{KBD}. Additionnally, it +# encloses case-sensitive special keys (SPC, RET...) within @key{...}. +#+macro: kbd (eval (let ((case-fold-search nil) (regexp (regexp-opt '("SPC" "RET" "LFD" "TAB" "BS" "ESC" "DELETE" "SHIFT" "Ctrl" "Meta" "Alt" "Cmd" "Super" "UP" "LEFT" "RIGHT" "DOWN") 'words))) (format "@@texinfo:@kbd{@@%s@@texinfo:}@@" (replace-regexp-in-string regexp "@@texinfo:@key{@@\\&@@texinfo:}@@" $1 t)))) + +* Footnotes + +[fn:1] See the variable ~org-special-ctrl-a/e~ to configure special +behavior of {{{kbd(C-a)}}} and {{{kbd(C-e)}}} in headlines. + +[fn:2] If you do not want the line to be split, customize the variable +~org-M-RET-may-split-line~. + +[fn:3] See also the variable ~org-show-context-detail~ to decide how +much context is shown around each match. + +[fn:4] The corresponding in-buffer setting is =#+STARTUP: logdone=. + +[fn:5] The corresponding in-buffer setting is =#+STARTUP: +logenotedone=. + +[fn:6] As with all these in-buffer settings, pressing {{{kbd(C-c +C-c)}}} activates any changes in the line. + +[fn:7] This is quite different from what is normally understood by +/scheduling a meeting/, which is done in Org by just inserting a time +stamp without keyword. + +[fn:8] It will still be listed on that date after it has been marked +as done. If you do not like this, set the variable +~org-agenda-skip-scheduled-if-done~. + +[fn:9] Using capture templates, you get finer control over capture +locations. See [[*Capture templates]]. + +[fn:10] If you need one of these sequences literally, escape the =%= +with a backslash. diff --git a/doc/orgguide.texi b/doc/orgguide.texi deleted file mode 100644 index 580fb7f..0000000 --- a/doc/orgguide.texi +++ /dev/null @@ -1,2699 +0,0 @@ -\input texinfo -@c %**start of header -@setfilename ../../info/orgguide -@settitle The compact Org-mode Guide - -@include org-version.inc - -@c Use proper quote and backtick for code sections in PDF output -@c Cf. Texinfo manual 14.2 -@set txicodequoteundirected -@set txicodequotebacktick - -@c Version and Contact Info -@set MAINTAINERSITE @uref{https://orgmode.org,maintainers webpage} -@set AUTHOR Carsten Dominik -@set MAINTAINER Carsten Dominik -@set MAINTAINEREMAIL @email{carsten at orgmode dot org} -@set MAINTAINERCONTACT @uref{mailto:carsten at orgmode dot org,contact the maintainer} -@c %**end of header -@finalout - -@c Macro definitions -@iftex -@c @hyphenation{time-stamp time-stamps time-stamp-ing time-stamp-ed} -@end iftex - -@c Subheadings inside a table. -@macro tsubheading{text} -@ifinfo -@subsubheading \text\ -@end ifinfo -@ifnotinfo -@item @b{\text\} -@end ifnotinfo -@end macro - -@macro seealso{text} -@noindent -@b{Further reading}@*@noindent \text\ -@end macro -@copying - -Copyright @copyright{} 2010--2019 Free Software Foundation - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 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 full Org manual, which is distributed together with the compact -guide. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@dircategory Emacs -@direntry -* Org Mode Guide: (orgguide). Abbreviated Org-mode Manual -@end direntry - -@titlepage -@title The compact Org-mode Guide - -@subtitle Release @value{VERSION} -@author by Carsten Dominik - -@c The following two commands start the copyright page. -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@c Output the table of contents at the beginning. -@shortcontents - -@ifnottex -@node Top, Introduction, (dir), (dir) -@top Org Mode Guide - -@insertcopying -@end ifnottex - -@menu -* Introduction:: Getting started -* Document Structure:: A tree works like your brain -* Tables:: Pure magic for quick formatting -* Hyperlinks:: Notes in context -* TODO Items:: Every tree branch can be a TODO item -* Tags:: Tagging headlines and matching sets of tags -* Properties:: Properties -* Dates and Times:: Making items useful for planning -* Capture - Refile - Archive:: The ins and outs for projects -* Agenda Views:: Collecting information into views -* Markup:: Prepare text for rich export -* Exporting:: Sharing and publishing of notes -* Publishing:: Create a web site of linked Org files -* Working With Source Code:: Source code snippets embedded in Org -* Miscellaneous:: All the rest which did not fit elsewhere - -* GNU Free Documentation License:: This manual license. - -@detailmenu - --- The Detailed Node Listing --- - -Introduction - -* Preface:: Welcome -* Installation:: How to install a downloaded version of Org -* Activation:: How to activate Org for certain buffers -* Feedback:: Bug reports, ideas, patches etc. - -Document Structure - -* Outlines:: Org is based on Outline mode -* Headlines:: How to typeset Org tree headlines -* Visibility cycling:: Show and hide, much simplified -* Motion:: Jumping to other headlines -* Structure editing:: Changing sequence and level of headlines -* Sparse trees:: Matches embedded in context -* Plain lists:: Additional structure within an entry -* Footnotes:: How footnotes are defined in Org's syntax - -Hyperlinks - -* Link format:: How links in Org are formatted -* Internal links:: Links to other places in the current file -* External links:: URL-like links to the world -* Handling links:: Creating, inserting and following -* Targeted links:: Point at a location in a file - -TODO Items - -* Using TODO states:: Setting and switching states -* Multi-state workflows:: More than just on/off -* Progress logging:: Dates and notes for progress -* Priorities:: Some things are more important than others -* Breaking down tasks:: Splitting a task into manageable pieces -* Checkboxes:: Tick-off lists - -Progress logging - -* Closing items:: When was this entry marked DONE? -* Tracking TODO state changes:: When did the status change? - -Tags - -* Tag inheritance:: Tags use the tree structure of the outline -* Setting tags:: How to assign tags to a headline -* Tag groups:: Use one tag to search for several tags -* Tag searches:: Searching for combinations of tags - -Dates and Times - -* Timestamps:: Assigning a time to a tree entry -* Creating timestamps:: Commands which insert timestamps -* Deadlines and scheduling:: Planning your work -* Clocking work time:: Tracking how long you spend on a task - -Capture - Refile - Archive - -* Capture:: Capturing new stuff -* Refile and copy:: Moving a tree from one place to another -* Archiving:: What to do with finished projects - -Capture - -* Setting up a capture location:: Where notes will be stored -* Using capture:: Commands to invoke and terminate capture -* Capture templates:: Define the outline of different note types - -Agenda Views - -* Agenda files:: Files being searched for agenda information -* Agenda dispatcher:: Keyboard access to agenda views -* Built-in agenda views:: What is available out of the box? -* Agenda commands:: Remote editing of Org trees -* Custom agenda views:: Defining special searches and views - -The built-in agenda views - -* Weekly/daily agenda:: The calendar page with current tasks -* Global TODO list:: All unfinished action items -* Matching tags and properties:: Structured information with fine-tuned search -* Search view:: Find entries by searching for text - -Markup for rich export - -* Structural markup elements:: The basic structure as seen by the exporter -* Images and tables:: Images, tables and caption mechanism -* Literal examples:: Source code examples with special formatting -* Include files:: Include additional files into a document -* Embedded @LaTeX{}:: @LaTeX{} can be freely used inside Org documents - -Structural markup elements - -* Document title:: Where the title is taken from -* Headings and sections:: The document structure as seen by the exporter -* Table of contents:: The if and where of the table of contents -* Paragraphs:: Paragraphs -* Emphasis and monospace:: Bold, italic, etc. -* Comment lines:: What will *not* be exported - -Exporting - -* Export options:: Per-file export settings -* The export dispatcher:: How to access exporter commands -* ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding -* HTML export:: Exporting to HTML -* @LaTeX{} and PDF export:: Exporting to @LaTeX{}, and processing to PDF -* iCalendar export:: Exporting to iCalendar - -Miscellaneous - -* Completion:: M-TAB knows what you need -* Clean view:: Getting rid of leading stars in the outline -* MobileOrg:: Org-mode on the iPhone - -@end detailmenu -@end menu - -@node Introduction, Document Structure, Top, Top -@chapter Introduction - -@menu -* Preface:: Welcome -* Installation:: How to install a downloaded version of Org -* Activation:: How to activate Org for certain buffers -* Feedback:: Bug reports, ideas, patches etc. -@end menu - -@node Preface, Installation, Introduction, Introduction -@section Preface - -Org is a mode for keeping notes, maintaining TODO lists, and doing project -planning with a fast and effective plain-text system. It is also an -authoring and publishing system, and it supports working with source code for -literal programming and reproducible research. - -@i{This document is a much compressed derivative of the -@uref{https://orgmode.org/index.html#sec-4_1, comprehensive Org-mode manual}. -It contains all basic features and commands, along with important hints for -customization. It is intended for beginners who would shy back from a 200 -page manual because of sheer size.} - -@node Installation, Activation, Preface, Introduction -@section Installation - -@b{Important:} @i{If you are using a version of Org that is part of the Emacs -distribution, please skip this section and go directly to @ref{Activation}.} - -If you have downloaded Org from the Web, either as a distribution @file{.zip} -or @file{.tar} file, or as a Git archive, it is best to run it directly from -the distribution directory. You need to add the @file{lisp} subdirectories -to the Emacs load path. To do this, add the following line to @file{.emacs}: - -@smallexample -(setq load-path (cons "~/path/to/orgdir/lisp" load-path)) -(setq load-path (cons "~/path/to/orgdir/contrib/lisp" load-path)) -@end smallexample - -@noindent -If you have been using git or a tar ball to get Org, you need to -run the following command to generate autoload information. -command: - -@smallexample -make autoloads -@end smallexample - -@node Activation, Feedback, Installation, Introduction -@section Activation - -Add the following lines to your @file{.emacs} file. The last four lines -define @emph{global} keys for some commands --- please choose suitable keys -yourself. - -@smalllisp -;; The following lines are always needed. Choose your own keys. -(global-set-key "\C-cl" 'org-store-link) -(global-set-key "\C-ca" 'org-agenda) -(global-set-key "\C-cc" 'org-capture) -(global-set-key "\C-cb" 'org-switchb) -@end smalllisp - -Files with extension @samp{.org} will be put into Org mode automatically. - -@node Feedback, , Activation, Introduction -@section Feedback - -If you find problems with Org, or if you have questions, remarks, or ideas -about it, please mail to the Org mailing list @email{emacs-orgmode@@gnu.org}. -For information on how to submit bug reports, see the main manual. - -@node Document Structure, Tables, Introduction, Top -@chapter Document Structure - -Org is based on Outline mode and provides flexible commands to -edit the structure of the document. - -@menu -* Outlines:: Org is based on Outline mode -* Headlines:: How to typeset Org tree headlines -* Visibility cycling:: Show and hide, much simplified -* Motion:: Jumping to other headlines -* Structure editing:: Changing sequence and level of headlines -* Sparse trees:: Matches embedded in context -* Plain lists:: Additional structure within an entry -* Footnotes:: How footnotes are defined in Org's syntax -@end menu - -@node Outlines, Headlines, Document Structure, Document Structure -@section Outlines - -Org is implemented on top of Outline mode. Outlines allow a -document to be organized in a hierarchical structure, which (at least -for me) is the best representation of notes and thoughts. An overview -of this structure is achieved by folding (hiding) large parts of the -document to show only the general document structure and the parts -currently being worked on. Org greatly simplifies the use of -outlines by compressing the entire show/hide functionality into a single -command, @command{org-cycle}, which is bound to the @key{TAB} key. - -@node Headlines, Visibility cycling, Outlines, Document Structure -@section Headlines - -Headlines define the structure of an outline tree. The headlines in -Org start with one or more stars, on the left margin@footnote{See -the variable @code{org-special-ctrl-a/e} to configure special behavior -of @kbd{C-a} and @kbd{C-e} in headlines.}. For example: - -@smallexample -* Top level headline -** Second level -*** 3rd level - some text -*** 3rd level - more text - -* Another top level headline -@end smallexample - -@noindent Note that a headline named after @code{org-footnote-section}, -which defaults to @samp{Footnotes}, is considered as special. A subtree with -this headline will be silently ignored by exporting functions. - -Some people find the many stars too noisy and would prefer an -outline that has whitespace followed by a single star as headline -starters. @ref{Clean view}, describes a setup to realize this. - -@node Visibility cycling, Motion, Headlines, Document Structure -@section Visibility cycling - -Outlines make it possible to hide parts of the text in the buffer. -Org uses just two commands, bound to @key{TAB} and -@kbd{S-@key{TAB}} to change the visibility in the buffer. - -@table @kbd -@item @key{TAB} -@emph{Subtree cycling}: Rotate current subtree among the states - -@smallexample -,-> FOLDED -> CHILDREN -> SUBTREE --. -'-----------------------------------' -@end smallexample - -When called with a prefix argument (@kbd{C-u @key{TAB}}) or with the shift -key, global cycling is invoked. - -@item S-@key{TAB} @r{and} C-u @key{TAB} -@emph{Global cycling}: Rotate the entire buffer among the states - -@smallexample -,-> OVERVIEW -> CONTENTS -> SHOW ALL --. -'--------------------------------------' -@end smallexample - -@item C-u C-u C-u @key{TAB} -Show all, including drawers. -@end table - -When Emacs first visits an Org file, the global state is set to -OVERVIEW, i.e.@: only the top level headlines are visible. This can be -configured through the variable @code{org-startup-folded}, or on a -per-file basis by adding a startup keyword @code{overview}, @code{content}, -@code{showall}, like this: - -@smallexample -#+STARTUP: content -@end smallexample - - -@node Motion, Structure editing, Visibility cycling, Document Structure -@section Motion -The following commands jump to other headlines in the buffer. - -@table @kbd -@item C-c C-n -Next heading. -@item C-c C-p -Previous heading. -@item C-c C-f -Next heading same level. -@item C-c C-b -Previous heading same level. -@item C-c C-u -Backward to higher level heading. -@end table - -@node Structure editing, Sparse trees, Motion, Document Structure -@section Structure editing - -@table @kbd -@item M-@key{RET} -Insert new heading with same level as current. If the cursor is in a plain -list item, a new item is created (@pxref{Plain lists}). When this command is -used in the middle of a line, the line is split and the rest of the line -becomes the new headline@footnote{If you do not want the line to be split, -customize the variable @code{org-M-RET-may-split-line}.}. -@item M-S-@key{RET} -Insert new TODO entry with same level as current heading. -@item @key{TAB} @r{in new, empty entry} -In a new entry with no text yet, @key{TAB} will cycle through reasonable -levels. -@item M-@key{left}@r{/}@key{right} -Promote/demote current heading by one level. -@item M-S-@key{left}@r{/}@key{right} -Promote/demote the current subtree by one level. -@item M-S-@key{up}@r{/}@key{down} -Move subtree up/down (swap with previous/next subtree of same -level). -@item C-c C-w -Refile entry or region to a different location. @xref{Refile and copy}. -@item C-x n s/w -Narrow buffer to current subtree / widen it again -@end table - -When there is an active region (Transient Mark mode), promotion and -demotion work on all headlines in the region. - -@node Sparse trees, Plain lists, Structure editing, Document Structure -@section Sparse trees - -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 -variable @code{org-show-context-detail} to decide 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: - -@table @kbd -@item C-c / -This prompts for an extra key to select a sparse-tree creating command. -@item C-c / r -Occur. Prompts for a regexp and shows a sparse tree with all matches. Each -match is also highlighted; the highlights disappear by pressing @kbd{C-c C-c}. -@end table - -The other sparse tree commands select headings based on TODO keywords, -tags, or properties and will be discussed later in this manual. - -@node Plain lists, Footnotes, Sparse trees, Document Structure -@section Plain lists - -Within an entry of the outline tree, hand-formatted lists can provide -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 lists, unordered lists, and description lists. -@itemize @bullet -@item -@emph{Unordered} list items start with @samp{-}, @samp{+}, or -@samp{*} as bullets. -@item -@emph{Ordered} list items start with @samp{1.} or @samp{1)}. -@item -@emph{Description} list use @samp{ :: } to separate the @emph{term} from the -description. -@end itemize - -Items belonging to the same list must have the same indentation on the first -line. An item ends before the next line that is indented like its -bullet/number, or less. A list ends when all items are closed, or before two -blank lines. An example: - -@smallexample -@group -** Lord of the Rings - My favorite scenes are (in this order) - 1. The attack of the Rohirrim - 2. Eowyn's fight with the witch king - + this was already my favorite scene in the book - + I really like Miranda Otto. - Important actors in this film are: - - @b{Elijah Wood} :: He plays Frodo - - @b{Sean Astin} :: He plays Sam, Frodo's friend. -@end group -@end smallexample - -The following commands act on items when the cursor is in the first line of -an item (the line with the bullet or number). - -@table @kbd -@item @key{TAB} -Items can be folded just like headline levels. -@item M-@key{RET} -Insert new item at current level. With a prefix argument, force a new -heading (@pxref{Structure editing}). -@item M-S-@key{RET} -Insert a new item with a checkbox (@pxref{Checkboxes}). -@item M-S-@key{up}@r{/}@key{down} -Move the item including subitems up/down (swap with previous/next item -of same indentation). If the list is ordered, renumbering is -automatic. -@item M-@key{left}@r{/}M-@key{right} -Decrease/increase the indentation of an item, leaving children alone. -@item M-S-@key{left}@r{/}@key{right} -Decrease/increase the indentation of the item, including subitems. -@item C-c C-c -If there is a checkbox (@pxref{Checkboxes}) in the item line, toggle the -state of the checkbox. Also verify bullets and indentation consistency in -the whole list. -@item C-c - -Cycle the entire list level through the different itemize/enumerate bullets -(@samp{-}, @samp{+}, @samp{*}, @samp{1.}, @samp{1)}). -@end table - -@node Footnotes, , Plain lists, Document Structure -@section Footnotes - -A footnote is defined in a paragraph that is started by a footnote marker in -square brackets in column 0, no indentation allowed. The footnote reference -is simply the marker in square brackets, inside text. For example: - -@smallexample -The Org homepage[fn:1] now looks a lot better than it used to. -... -[fn:1] The link is: https://orgmode.org -@end smallexample - -@noindent -The following commands handle footnotes: - -@table @kbd -@item C-c C-x f -The footnote action command. When the cursor is on a footnote reference, -jump to the definition. When it is at a definition, jump to the (first) -reference. Otherwise, create a new footnote. When this command is called -with a prefix argument, a menu of additional options including renumbering is -offered. - -@item C-c C-c -Jump between definition and reference. -@end table - -@seealso{ -@uref{https://orgmode.org/manual/Document-structure.html#Document-structure, -Chapter 2 of the manual}@* -@uref{http://sachachua.com/wp/2008/01/outlining-your-notes-with-org/, -Sacha Chua's tutorial}} - - -@node Tables, Hyperlinks, Document Structure, Top -@chapter Tables - -Org comes with a fast and intuitive table editor. Spreadsheet-like -calculations are supported in connection with the Emacs @file{calc} -package -@ifinfo -(@pxref{Top,Calc,,Calc,Gnu Emacs Calculator Manual}). -@end ifinfo -@ifnotinfo -(see the Emacs Calculator manual for more information about the Emacs -calculator). -@end ifnotinfo - -Org makes it easy to format tables in plain ASCII. Any line with -@samp{|} as the first non-whitespace character is considered part of a -table. @samp{|} is also the column separator. A table might look like -this: - -@smallexample -| Name | Phone | Age | -|-------+-------+-----| -| Peter | 1234 | 17 | -| Anna | 4321 | 25 | -@end smallexample - -A table is re-aligned automatically each time you press @key{TAB} or -@key{RET} or @kbd{C-c C-c} inside the table. @key{TAB} also moves to -the next field (@key{RET} to the next row) and creates new table rows -at the end of the table or before horizontal lines. The indentation -of the table is set by the first line. Any line starting with -@samp{|-} is considered as a horizontal separator line and will be -expanded on the next re-align to span the whole table width. So, to -create the above table, you would only type - -@smallexample -|Name|Phone|Age| -|- -@end smallexample - -@noindent -and then press @key{TAB} to align the table and start filling in -fields. Even faster would be to type @code{|Name|Phone|Age} followed by -@kbd{C-c @key{RET}}. - -When typing text into a field, Org treats @key{DEL}, -@key{Backspace}, and all character keys in a special way, so that -inserting and deleting avoids shifting other fields. Also, when -typing @emph{immediately after the cursor was moved into a new field -with @kbd{@key{TAB}}, @kbd{S-@key{TAB}} or @kbd{@key{RET}}}, the -field is automatically made blank. - -@table @kbd -@tsubheading{Creation and conversion} -@item C-c | -Convert the active region to table. If every line contains at least one TAB -character, the function assumes that the material is tab separated. If every -line contains a comma, comma-separated values (CSV) are assumed. If not, -lines are split at whitespace into fields. -@* -If there is no active region, this command creates an empty Org -table. But it's easier just to start typing, like -@kbd{|Name|Phone|Age C-c @key{RET}}. - -@tsubheading{Re-aligning and field motion} -@item C-c C-c -Re-align the table without moving the cursor. -@c -@item @key{TAB} -Re-align the table, move to the next field. Creates a new row if -necessary. -@c -@item S-@key{TAB} -Re-align, move to previous field. -@c -@item @key{RET} -Re-align the table and move down to next row. Creates a new row if -necessary. -@c -@item S-@key{up} -@itemx S-@key{down} -@itemx S-@key{left} -@itemx S-@key{right} -Move a cell up, down, left, and right by swapping with adjacent cell. - -@tsubheading{Column and row editing} -@item M-@key{left} -@itemx M-@key{right} -Move the current column left/right. -@c -@item M-S-@key{left} -Kill the current column. -@c -@item M-S-@key{right} -Insert a new column to the left of the cursor position. -@c -@item M-@key{up} -@itemx M-@key{down} -Move the current row up/down. -@c -@item M-S-@key{up} -Kill the current row or horizontal line. -@c -@item M-S-@key{down} -Insert a new row above the current row. With a prefix argument, the line is -created below the current one. -@c -@item C-c - -Insert a horizontal line below current row. With a prefix argument, the line -is created above the current line. -@c -@item C-c @key{RET} -Insert a horizontal line below current row, and move the cursor into the row -below that line. -@c -@item C-c ^ -Sort the table lines in the region. The position of point indicates the -column to be used for sorting, and the range of lines is the range -between the nearest horizontal separator lines, or the entire table. - -@end table - -@seealso{ -@uref{https://orgmode.org/manual/Tables.html#Tables, Chapter 3 of the -manual}@* -@uref{https://orgmode.org/worg/org-tutorials/tables.html, Bastien's -table tutorial}@* -@uref{https://orgmode.org/worg/org-tutorials/org-spreadsheet-intro.html, -Bastien's spreadsheet tutorial}@* -@uref{https://orgmode.org/worg/org-tutorials/org-plot.html, Eric's plotting tutorial}} - -@node Hyperlinks, TODO Items, Tables, Top -@chapter Hyperlinks - -Like HTML, Org provides links inside a file, external links to -other files, Usenet articles, emails, and much more. - -@menu -* Link format:: How links in Org are formatted -* Internal links:: Links to other places in the current file -* External links:: URL-like links to the world -* Handling links:: Creating, inserting and following -* Targeted links:: Point at a location in a file -@end menu - -@node Link format, Internal links, Hyperlinks, Hyperlinks -@section Link format - -Org will recognize plain URL-like links and activate them as -clickable links. The general link format, however, looks like this: - -@smallexample -[[link][description]] @r{or alternatively} [[link]] -@end smallexample - -@noindent -Once a link in the buffer is complete (all brackets present), Org will change -the display so that @samp{description} is displayed instead of -@samp{[[link][description]]} and @samp{link} is displayed instead of -@samp{[[link]]}. To edit the invisible @samp{link} part, use @kbd{C-c -C-l} with the cursor on the link. - -@node Internal links, External links, Link format, Hyperlinks -@section Internal links - -If the link does not look like a URL, it is considered to be internal in the -current file. The most important case is a link like -@samp{[[#my-custom-id]]} which will link to the entry with the -@code{CUSTOM_ID} property @samp{my-custom-id}. - -Links such as @samp{[[My Target]]} or @samp{[[My Target][Find my target]]} -lead to a text search in the current file for the corresponding target which -looks like @samp{<<My Target>>}. - -Internal links will be used to reference their destination, through links or -numbers, when possible. - -@node External links, Handling links, Internal links, Hyperlinks -@section External links - -Org supports links to files, websites, Usenet and email messages, -BBDB database entries and links to both IRC conversations and their -logs. External links are URL-like locators. They start with a short -identifying string followed by a colon. There can be no space after -the colon. Here are some examples: - -@smallexample -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} -file:projects.org @r{another Org file} -docview:papers/last.pdf::NNN @r{open file in doc-view mode at page NNN} -id:B7423F4D-2E8A-471B-8810-C40F074717E9 @r{Link to heading by ID} -news:comp.emacs @r{Usenet link} -mailto:adent@@galaxy.net @r{Mail link} -vm:folder @r{VM folder link} -vm:folder#id @r{VM message link} -wl:folder#id @r{WANDERLUST message link} -mhe:folder#id @r{MH-E message link} -rmail:folder#id @r{RMAIL message link} -gnus:group#id @r{Gnus article link} -bbdb:R.*Stallman @r{BBDB link (with regexp)} -irc:/irc.com/#emacs/bob @r{IRC link} -info:org:External%20links @r{Info node link (with encoded space)} -@end smallexample - -A link should be enclosed in double brackets and may contain a -descriptive text to be displayed instead of the URL (@pxref{Link -format}), for example: - -@smallexample -[[http://www.gnu.org/software/emacs/][GNU Emacs]] -@end smallexample - -@noindent -If the description is a file name or URL that points to an image, HTML export -(@pxref{HTML export}) will inline the image as a clickable button. If there -is no description at all and the link points to an image, that image will be -inlined into the exported HTML file. - -@node Handling links, Targeted links, External links, Hyperlinks -@section Handling links - -Org provides methods to create a link in the correct syntax, to -insert it into an Org file, and to follow the link. - -@table @kbd -@item C-c l -Store a link to the current location. This is a @emph{global} command (you -must create the key binding yourself) which can be used in any buffer to -create a link. The link will be stored for later insertion into an Org -buffer (see below). -@c -@item C-c C-l -Insert a link. This prompts for a link to be inserted into the buffer. You -can just type a link, or use history keys @key{up} and @key{down} to access -stored links. You will be prompted for the description part of the link. -When called with a @kbd{C-u} prefix argument, file name completion is used to -link to a file. -@c -@item C-c C-l @r{(with cursor on existing link)} -When the cursor is on an existing link, @kbd{C-c C-l} allows you to edit the -link and description parts of the link. -@c -@item C-c C-o @r{or} mouse-1 @r{or} mouse-2 -Open link at point. -@item C-c & -Jump back to a recorded position. A position is recorded by the -commands following internal links, and by @kbd{C-c %}. Using this -command several times in direct succession moves through a ring of -previously recorded positions. -@c -@end table - -@node Targeted links, , Handling links, Hyperlinks -@section Targeted links - -File links can contain additional information to make Emacs jump to a -particular location in the file when following a link. This can be a -line number or a search option after a double colon. - -Here is the syntax of the different ways to attach a search to a file -link, together with an explanation: - -@smallexample -[[file:~/code/main.c::255]] @r{Find line 255} -[[file:~/xx.org::My Target]] @r{Find @samp{<<My Target>>}} -[[file:~/xx.org::#my-custom-id]] @r{Find entry with custom id} -@end smallexample - -@seealso{ -@uref{https://orgmode.org/manual/Hyperlinks.html#Hyperlinks, Chapter 4 of the -manual}} - -@node TODO Items, Tags, Hyperlinks, Top -@chapter TODO Items - -Org mode does not require TODO lists to live in separate documents. Instead, -TODO items are part of a notes file, because TODO items usually -come up while taking notes! With Org mode, simply mark any entry in a tree -as being a TODO item. In this way, information is not duplicated, and TODO -items remain in the context from which they emerged. - -Org mode provides methods to give you an overview of all the things that you -have to do, collected from many files. - -@menu -* Using TODO states:: Setting and switching states -* Multi-state workflows:: More than just on/off -* Progress logging:: Dates and notes for progress -* Priorities:: Some things are more important than others -* Breaking down tasks:: Splitting a task into manageable pieces -* Checkboxes:: Tick-off lists -@end menu - -@node Using TODO states, Multi-state workflows, TODO Items, TODO Items -@section Using TODO states - -Any headline becomes a TODO item when it starts with the word -@samp{TODO}, for example: - -@smallexample -*** TODO Write letter to Sam Fortune -@end smallexample - -@noindent -The most important commands to work with TODO entries are: - -@table @kbd -@item C-c C-t -Rotate the TODO state of the current item among - -@smallexample -(unmarked) -> TODO -> DONE -> (unmarked) -@end smallexample - -The same rotation can also be done ``remotely'' from the agenda buffers with -the @kbd{t} command key (@pxref{Agenda commands}). - -@item S-@key{right}@r{/}@key{left} -Select the following/preceding TODO state, similar to cycling. -@item C-c / t -View TODO items in a @emph{sparse tree} (@pxref{Sparse trees}). Folds the -buffer, but shows all TODO items and the headings hierarchy above -them. -@item C-c a t -Show the global TODO list. Collects the TODO items from all agenda files -(@pxref{Agenda Views}) into a single buffer. @xref{Global TODO list}, for -more information. -@item S-M-@key{RET} -Insert a new TODO entry below the current one. -@end table - -@noindent -Changing a TODO state can also trigger tag changes. See the docstring of the -option @code{org-todo-state-tags-triggers} for details. - -@node Multi-state workflows, Progress logging, Using TODO states, TODO Items -@section Multi-state workflows - -You can use TODO keywords to indicate @emph{sequential} working progress -states: - -@smalllisp -(setq org-todo-keywords - '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED"))) -@end smalllisp - -The vertical bar separates the TODO keywords (states that @emph{need 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. 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. Sometimes you -may want to use different sets of TODO keywords in parallel. For example, -you may want to have the basic @code{TODO}/@code{DONE}, but also a workflow -for bug fixing. Your setup would then look like this: - -@smalllisp -(setq org-todo-keywords - '((sequence "TODO(t)" "|" "DONE(d)") - (sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)"))) -@end smalllisp - -The keywords should all be different, this helps Org mode to keep track of -which subsequence should be used for a given entry. The example also shows -how to define keys for fast access of a particular state, by adding a letter -in parenthesis after each keyword---you will be prompted for the key after -@kbd{C-c C-t}. - -To define TODO keywords that are valid only in a single file, use the -following text anywhere in the file. - -@smallexample -#+TODO: TODO(t) | DONE(d) -#+TODO: REPORT(r) BUG(b) KNOWNCAUSE(k) | FIXED(f) -#+TODO: | CANCELED(c) -@end smallexample - -After changing one of these lines, use @kbd{C-c C-c} with the cursor still in -the line to make the changes known to Org mode. - -@node Progress logging, Priorities, Multi-state workflows, TODO Items -@section Progress logging - -Org mode can automatically record a timestamp and possibly a note when -you mark a TODO item as DONE, or even each time you change the state of -a TODO item. This system is highly configurable; settings can be on a -per-keyword basis and can be localized to a file or even a subtree. For -information on how to clock working time for a task, see @ref{Clocking -work time}. - -@menu -* Closing items:: When was this entry marked DONE? -* Tracking TODO state changes:: When did the status change? -@end menu - -@node Closing items, Tracking TODO state changes, Progress logging, Progress logging -@unnumberedsubsec Closing items - -The most basic logging is to keep track of @emph{when} a certain TODO -item was finished. This is achieved with@footnote{The corresponding -in-buffer setting is: @code{#+STARTUP: logdone}}. - -@smalllisp -(setq org-log-done 'time) -@end smalllisp - -@noindent -Then each time you turn an entry from a TODO (not-done) state into any of the -DONE states, a line @samp{CLOSED: [timestamp]} will be inserted just after -the headline. If you want to record a note along with the timestamp, -use@footnote{The corresponding in-buffer setting is: @code{#+STARTUP: -lognotedone}} - -@smalllisp -(setq org-log-done 'note) -@end smalllisp - -@noindent -You will then be prompted for a note, and that note will be stored below -the entry with a @samp{Closing Note} heading. - -@node Tracking TODO state changes, , Closing items, Progress logging -@unnumberedsubsec Tracking TODO state changes - -You might want to keep track of TODO state changes. You can either record -just a timestamp, or a time-stamped note for a change. These records will be -inserted after the headline as an itemized list. When taking a lot of notes, -you might want to get the notes out of the way into a drawer. Customize the -variable @code{org-log-into-drawer} to get this behavior. - -For state logging, Org mode expects configuration on a per-keyword basis. -This is achieved by adding special markers @samp{!} (for a timestamp) and -@samp{@@} (for a note) in parentheses after each keyword. For example: -@smallexample -#+TODO: TODO(t) WAIT(w@@/!) | DONE(d!) CANCELED(c@@) -@end smallexample -@noindent -will define TODO keywords and fast access keys, and also request that a time -is recorded when the entry is set to DONE, and that a note is recorded when -switching to WAIT or CANCELED. The same syntax works also when setting -@code{org-todo-keywords}. - -@node Priorities, Breaking down tasks, Progress logging, TODO Items -@section Priorities - -If you use Org mode extensively, you may end up with enough TODO items that -it starts to make sense to prioritize them. Prioritizing can be done by -placing a @emph{priority cookie} into the headline of a TODO item, like this - -@smallexample -*** TODO [#A] Write letter to Sam Fortune -@end smallexample - -@noindent -Org mode supports three priorities: @samp{A}, @samp{B}, and @samp{C}. -@samp{A} is the highest, @samp{B} the default if none is given. Priorities -make a difference only in the agenda. - -@table @kbd -@item @kbd{C-c ,} -Set the priority of the current headline. Press @samp{A}, @samp{B} or -@samp{C} to select a priority, or @key{SPC} to remove the cookie. -@c -@item S-@key{up}/@key{dwn} -Increase/decrease priority of current headline -@end table - -@node Breaking down tasks, Checkboxes, Priorities, TODO Items -@section Breaking tasks down into subtasks - -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. 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 updated each time -the TODO status of a child changes, or when pressing @kbd{C-c C-c} on the -cookie. For example: - -@smallexample -* Organize Party [33%] -** TODO Call people [1/2] -*** TODO Peter -*** DONE Sarah -** TODO Buy food -** DONE Talk to neighbor -@end smallexample - -@node Checkboxes, , Breaking down tasks, TODO Items -@section Checkboxes - -Every item in a plain list (@pxref{Plain lists}) can be made into a checkbox -by starting it with the string @samp{[ ]}. Checkboxes are not included in -the global TODO list, so they are often great to split a task into a number -of simple steps. -Here is an example of a checkbox list. - -@smallexample -* TODO Organize party [1/3] - - [-] call people [1/2] - - [ ] Peter - - [X] Sarah - - [X] order food -@end smallexample - -Checkboxes work hierarchically, so if a checkbox item has children that -are checkboxes, toggling one of the children checkboxes will make the -parent checkbox reflect if none, some, or all of the children are -checked. - -@noindent -The following commands work with checkboxes: - -@table @kbd -@item C-c C-c -Toggle checkbox status or (with prefix arg) checkbox presence at point. -@item M-S-@key{RET} -Insert a new item with a checkbox. -This works only if the cursor is already in a plain list item -(@pxref{Plain lists}). -@end table - -@seealso{ -@uref{https://orgmode.org/manual/TODO-items.html#TODO-items, Chapter 5 of the manual}@* -@uref{https://orgmode.org/worg/org-tutorials/orgtutorial_dto.html, David -O'Toole's introductory tutorial}@* -@uref{http://members.optusnet.com.au/~charles57/GTD/gtd_workflow.html, -Charles Cave's GTD setup}} - -@node Tags, Properties, TODO Items, Top -@chapter Tags - -An excellent way to implement labels and contexts for cross-correlating -information is to assign @i{tags} to headlines. Org mode has extensive -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 @samp{:work:urgent:}. -Tags will by default be in bold face with the same color as the headline. - -@menu -* Tag inheritance:: Tags use the tree structure of the outline -* Setting tags:: How to assign tags to a headline -* Tag groups:: Use one tag to search for several tags -* Tag searches:: Searching for combinations of tags -@end menu - -@node Tag inheritance, Setting tags, Tags, Tags -@section Tag inheritance - -@i{Tags} make use of the hierarchical structure of outline trees. If a -heading has a certain tag, all subheadings will inherit the tag as -well. For example, in the list - -@smallexample -* Meeting with the French group :work: -** Summary by Frank :boss:notes: -*** TODO Prepare slides for him :action: -@end smallexample - -@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. You can also set tags that all entries in -a file should inherit just as if these tags were defined in a hypothetical -level zero that surrounds the entire file. Use a line like this@footnote{As -with all these in-buffer settings, pressing @kbd{C-c C-c} activates any -changes in the line.}: - -@smallexample -#+FILETAGS: :Peter:Boss:Secret: -@end smallexample - -@node Setting tags, Tag groups, Tag inheritance, Tags -@section Setting tags - -Tags can simply be typed into the buffer at the end of a headline. -After a colon, @kbd{M-@key{TAB}} offers completion on tags. There is -also a special command for inserting tags: - -@table @kbd -@item C-c C-q -Enter new tags for the current headline. Org mode will either offer -completion or a special single-key interface for setting tags, see -below. After pressing @key{RET}, the tags will be inserted and aligned -to @code{org-tags-column}. When called with a @kbd{C-u} prefix, all -tags in the current buffer will be aligned to that column, just to make -things look nice. -@item C-c C-c -When the cursor is in a headline, this does the same as @kbd{C-c C-q}. -@end table - -Org will support tag insertion based on a @emph{list of tags}. By -default this list is constructed dynamically, containing all tags -currently used in the buffer. You may also globally specify a hard list -of tags with the variable @code{org-tag-alist}. Finally you can set -the default tags for a given file with lines like - -@smallexample -#+TAGS: @@work @@home @@tennisclub -#+TAGS: laptop car pc sailboat -@end smallexample - -By default Org mode uses the standard minibuffer completion facilities for -entering tags. However, it also implements another, quicker, tag selection -method called @emph{fast tag selection}. This allows you to select and -deselect tags with just a single key press. For this to work well you should -assign unique letters to most of your commonly used tags. You can do this -globally by configuring the variable @code{org-tag-alist} in your -@file{.emacs} file. For example, you may find the need to tag many items in -different files with @samp{:@@home:}. In this case you can set something -like: - -@smalllisp -(setq org-tag-alist '(("@@work" . ?w) ("@@home" . ?h) ("laptop" . ?l))) -@end smalllisp - -@noindent -If the tag is only relevant to the file you are working on, then you -can instead set the TAGS option line as: - -@smallexample -#+TAGS: @@work(w) @@home(h) @@tennisclub(t) laptop(l) pc(p) -@end smallexample - -@node Tag groups, Tag searches, Setting tags, Tags -@section Tag groups - -@cindex group tags -@cindex tags, groups -In a set of mutually exclusive tags, the first tag can be defined as a -@emph{group tag}. When you search for a group tag, it will return matches -for all members in the group. In an agenda view, filtering by a group tag -will display headlines tagged with at least one of the members of the -group. This makes tag searches and filters even more flexible. - -You can set group tags by inserting a colon between the group tag and other -tags, like this: - -@example -#+TAGS: @{ @@read : @@read_book @@read_ebook @} -@end example - -In this example, @samp{@@read} is a @emph{group tag} for a set of three -tags: @samp{@@read}, @samp{@@read_book} and @samp{@@read_ebook}. - -You can also use the @code{:grouptags} keyword directly when setting -@var{org-tag-alist}, see the documentation of that variable. - -@kindex C-c C-x q -@vindex org-group-tags -If you want to ignore group tags temporarily, toggle group tags support -with @command{org-toggle-tags-groups}, bound to @kbd{C-c C-x q}. If you -want to disable tag groups completely, set @var{org-group-tags} to nil. - -@node Tag searches, , Tag groups, Tags -@section Tag searches - -Once a system of tags has been set up, it can be used to collect related -information into special lists. - -@table @kbd -@item C-c \ -@itemx C-c / m -Create a sparse tree with all headlines matching a tags search. With a -@kbd{C-u} prefix argument, ignore headlines that are not a TODO line. -@item C-c a m -Create a global list of tag matches from all agenda files. -@xref{Matching tags and properties}. -@item C-c a M -Create a global list of tag matches from all agenda files, but check -only TODO items and force checking subitems (see variable -@code{org-tags-match-list-sublevels}). -@end table - -These commands all prompt for a match string which allows basic Boolean logic -like @samp{+boss+urgent-project1}, to find entries with tags @samp{boss} and -@samp{urgent}, but not @samp{project1}, or @samp{Kathy|Sally} to find entries -which are tagged, like @samp{Kathy} or @samp{Sally}. The full syntax of the -search string is rich and allows also matching against TODO keywords, entry -levels and properties. For a complete description with many examples, see -@ref{Matching tags and properties}. - -@seealso{ -@uref{https://orgmode.org/manual/Tags.html#Tags, Chapter 6 of the manual}@* -@uref{http://sachachua.com/wp/2008/01/tagging-in-org-plus-bonus-code-for-timeclocks-and-tags/, -Sacha Chua's article about tagging in Org-mode}} - -@node Properties, Dates and Times, Tags, Top -@chapter Properties - -Properties are key-value pairs associated with an entry. They live in a -special drawer with the name @code{PROPERTIES}. Each -property is specified on a single line, with the key (surrounded by colons) -first, and the value after it: - -@smallexample -* CD collection -** Classic -*** Goldberg Variations - :PROPERTIES: - :Title: Goldberg Variations - :Composer: J.S. Bach - :Publisher: Deutsche Grammophon - :NDisks: 1 - :END: -@end smallexample - -You may define the allowed values for a particular property @samp{:Xyz:} -by setting a property @samp{:Xyz_ALL:}. This special property is -@emph{inherited}, so if you set it in a level 1 entry, it will apply to -the entire tree. When allowed values are defined, setting the -corresponding property becomes easier and is less prone to typing -errors. For the example with the CD collection, we can predefine -publishers and the number of disks in a box like this: - -@smallexample -* CD collection - :PROPERTIES: - :NDisks_ALL: 1 2 3 4 - :Publisher_ALL: "Deutsche Grammophon" Philips EMI - :END: -@end smallexample -or globally using @code{org-global-properties}, or file-wide like this: -@smallexample -#+PROPERTY: NDisks_ALL 1 2 3 4 -@end smallexample - -@table @kbd -@item C-c C-x p -Set a property. This prompts for a property name and a value. -@item C-c C-c d -Remove a property from the current entry. -@end table - -To create sparse trees and special lists with selection based on properties, -the same commands are used as for tag searches (@pxref{Tag searches}). The -syntax for the search string is described in @ref{Matching tags and -properties}. - -@table @kbd -@end table - -@seealso{ -@uref{https://orgmode.org/manual/Properties-and-columns.html#Properties-and-columns,Chapter -7 of the manual}@* -@uref{https://orgmode.org/worg/org-tutorials/org-column-view-tutorial.html,Bastien's -column view tutorial}} - -@node Dates and Times, Capture - Refile - Archive, Properties, Top -@chapter Dates and Times - -To assist project planning, TODO items can be labeled with a date and/or -a time. The specially formatted string carrying the date and time -information is called a @emph{timestamp} in Org mode. - -@menu -* Timestamps:: Assigning a time to a tree entry -* Creating timestamps:: Commands which insert timestamps -* Deadlines and scheduling:: Planning your work -* Clocking work time:: Tracking how long you spend on a task -@end menu - - -@node Timestamps, Creating timestamps, Dates and Times, Dates and Times -@section Timestamps - -A timestamp is a specification of a date (possibly with a time or a range of -times) in a special format, either @samp{<2003-09-16 Tue>} or -@samp{<2003-09-16 Tue 09:39>} or @samp{<2003-09-16 Tue 12:00-12:30>}. A -timestamp can appear anywhere in the headline or body of an Org tree entry. -Its presence causes entries to be shown on specific dates in the agenda -(@pxref{Weekly/daily agenda}). We distinguish: - -@noindent -@b{Plain timestamp; Event; Appointment}@* -A simple timestamp just assigns a date/time to an item. This is just -like writing down an appointment or event in a paper agenda. - -@smallexample -* Meet Peter at the movies - <2006-11-01 Wed 19:15> -* Discussion on climate change - <2006-11-02 Thu 20:00-22:00> -@end smallexample - -@noindent -@b{Timestamp with repeater interval}@* -A timestamp may contain a @emph{repeater interval}, indicating that it -applies not only on the given date, but again and again after a certain -interval of N days (d), weeks (w), months (m), or years (y). The -following will show up in the agenda every Wednesday: -@smallexample -* Pick up Sam at school - <2007-05-16 Wed 12:30 +1w> -@end smallexample - -@noindent -@b{Diary-style sexp entries}@* -For more complex date specifications, Org mode supports using the -special sexp diary entries implemented in the Emacs calendar/diary -package. For example -@smallexample -* The nerd meeting on every 2nd Thursday of the month - <%%(diary-float t 4 2)> -@end smallexample - -@noindent -@b{Time/Date range}@* -Two timestamps connected by @samp{--} denote a range. -@smallexample -** Meeting in Amsterdam - <2004-08-23 Mon>--<2004-08-26 Thu> -@end smallexample - -@noindent -@b{Inactive timestamp}@* -Just like a plain timestamp, but with square brackets instead of -angular ones. These timestamps are inactive in the sense that they do -@emph{not} trigger an entry to show up in the agenda. - -@smallexample -* Gillian comes late for the fifth time - [2006-11-01 Wed] -@end smallexample - - -@node Creating timestamps, Deadlines and scheduling, Timestamps, Dates and Times -@section Creating timestamps - -For Org mode to recognize timestamps, they need to be in the specific -format. All commands listed below produce timestamps in the correct -format. - -@table @kbd -@item C-c . -Prompt for a date and insert a corresponding timestamp. When the cursor is -at an existing timestamp in the buffer, the command is used to modify this -timestamp instead of inserting a new one. When this command is used twice in -succession, a time range is inserted. With a prefix, also add the current -time. -@c -@item C-c ! -Like @kbd{C-c .}, but insert an inactive timestamp that will not cause -an agenda entry. -@c -@item S-@key{left}@r{/}@key{right} -Change date at cursor by one day. -@c -@item S-@key{up}@r{/}@key{down} -Change the item under the cursor in a timestamp. The cursor can be on a -year, month, day, hour or minute. When the timestamp contains a time range -like @samp{15:30-16:30}, modifying the first time will also shift the second, -shifting the time block with constant length. To change the length, modify -the second time. -@end table - -When Org mode prompts for a date/time, it will accept any string containing -some date and/or time information, and intelligently interpret the string, -deriving defaults for unspecified information from the current date and time. -You can also select a date in the pop-up calendar. See the manual for more -information on how exactly the date/time prompt works. - -@node Deadlines and scheduling, Clocking work time, Creating timestamps, Dates and Times -@section Deadlines and scheduling - -A timestamp may be preceded by special keywords to facilitate planning: - -@noindent -@b{DEADLINE}@* -Meaning: the task (most likely a TODO item, though not necessarily) is supposed -to be finished on that date. -@table @kbd -@item C-c C-d -Insert @samp{DEADLINE} keyword along with a stamp, in the line following the -headline. -@end table - -On the deadline date, the task will be listed in the agenda. In -addition, the agenda for @emph{today} will carry a warning about the -approaching or missed deadline, starting -@code{org-deadline-warning-days} before the due date, and continuing -until the entry is marked DONE. An example: - -@smallexample -*** TODO write article about the Earth for the Guide - The editor in charge is [[bbdb:Ford Prefect]] - DEADLINE: <2004-02-29 Sun> -@end smallexample - - -@noindent -@b{SCHEDULED}@* -Meaning: you are @i{planning to start working} on that task on the given -date@footnote{This is quite different from what is normally understood by -@i{scheduling a meeting}, which is done in Org-mode by just inserting a time -stamp without keyword.}. - -@table @kbd -@item C-c C-s -Insert @samp{SCHEDULED} keyword along with a stamp, in the line following the -headline. -@end table - -The headline will be listed under the given date@footnote{It will still -be listed on that date after it has been marked DONE. If you don't like -this, set the variable @code{org-agenda-skip-scheduled-if-done}.}. In -addition, a reminder that the scheduled date has passed will be present -in the compilation for @emph{today}, until the entry is marked DONE. -I.e.@: the task will automatically be forwarded until completed. - -@smallexample -*** TODO Call Trillian for a date on New Years Eve. - SCHEDULED: <2004-12-25 Sat> -@end smallexample - -Some tasks need to be repeated again and again. Org mode helps to -organize such tasks using a so-called repeater in a DEADLINE, SCHEDULED, -or plain timestamp. In the following example -@smallexample -** TODO Pay the rent - DEADLINE: <2005-10-01 Sat +1m> -@end smallexample -@noindent -the @code{+1m} is a repeater; the intended interpretation is that the task -has a deadline on <2005-10-01> and repeats itself every (one) month starting -from that time. - -@node Clocking work time, , Deadlines and scheduling, Dates and Times -@section Clocking work time - -Org mode allows you to clock the time you spend on specific tasks in a -project. - -@table @kbd -@item C-c C-x C-i -Start the clock on the current item (clock-in). This inserts the CLOCK -keyword together with a timestamp. When called with a @kbd{C-u} prefix -argument, select the task from a list of recently clocked tasks. -@c -@item C-c C-x C-o -Stop the clock (clock-out). This inserts another timestamp at the same -location where the clock was last started. It also directly computes -the resulting time in inserts it after the time range as @samp{=> -HH:MM}. -@item C-c C-x C-e -Update the effort estimate for the current clock task. -@item C-c C-x C-q -Cancel the current clock. This is useful if a clock was started by -mistake, or if you ended up working on something else. -@item C-c C-x C-j -Jump to the entry that contains the currently running clock. With a -@kbd{C-u} prefix arg, select the target task from a list of recently clocked -tasks. -@item C-c C-x C-r -Insert a dynamic block containing a clock -report as an Org-mode table into the current file. When the cursor is -at an existing clock table, just update it. -@smallexample -#+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file -#+END: clocktable -@end smallexample -@noindent -For details about how to customize this view, see @uref{https://orgmode.org/manual/Clocking-work-time.html#Clocking-work-time,the manual}. -@item C-c C-c -Update dynamic block at point. The cursor needs to be in the -@code{#+BEGIN} line of the dynamic block. -@end table - -The @kbd{l} key may be used in the agenda (@pxref{Weekly/daily agenda}) to -show which tasks have been worked on or closed during a day. - -@seealso{ -@uref{https://orgmode.org/manual/Dates-and-times.html#Dates-and-times, -Chapter 8 of the manual}@* -@uref{http://members.optusnet.com.au/~charles57/GTD/org_dates/, Charles -Cave's Date and Time tutorial}@* -@uref{http://doc.norang.ca/org-mode.html#Clocking, Bernt Hansen's clocking workflow}} - -@node Capture - Refile - Archive, Agenda Views, Dates and Times, Top -@chapter Capture - Refile - Archive - -An important part of any organization system is the ability to quickly -capture new ideas and tasks, and to associate reference material with them. -Org defines a capture process to create tasks. Once in the system, tasks and -projects need to be moved around. Moving completed project trees to an -archive file keeps the system compact and fast. - -@menu -* Capture:: Capturing new stuff -* Refile and copy:: Moving a tree from one place to another -* Archiving:: What to do with finished projects -@end menu - -@node Capture, Refile and copy, Capture - Refile - Archive, Capture - Refile - Archive -@section Capture - -Org's lets you store quick notes with little interruption of your work flow. -You can define templates for new entries and associate them with different -targets for storing notes. - -@menu -* Setting up a capture location:: Where notes will be stored -* Using capture:: Commands to invoke and terminate capture -* Capture templates:: Define the outline of different note types -@end menu - -@node Setting up a capture location, Using capture, Capture, Capture -@unnumberedsubsec Setting up a capture location - -The following customization sets a default target@footnote{Using capture -templates, you get finer control over capture locations, see -@ref{Capture templates}.} file for notes, and defines a global -key for capturing new stuff. - -@example -(setq org-default-notes-file (concat org-directory "/notes.org")) -(define-key global-map "\C-cc" 'org-capture) -@end example - -@node Using capture, Capture templates, Setting up a capture location, Capture -@unnumberedsubsec Using capture - -@table @kbd -@item C-c c -Start a capture process, placing you into a narrowed indirect buffer to edit. -@item C-c C-c -Once you are done entering information into the capture buffer, -@kbd{C-c C-c} will return you to the window configuration before the capture -process, so that you can resume your work without further distraction. -@item C-c C-w -Finalize by moving the entry to a refile location (see section 9.2). -@item C-c C-k -Abort the capture process and return to the previous state. -@end table - -@node Capture templates, , Using capture, Capture -@unnumberedsubsec Capture templates - -You can use templates to generate different types of capture notes, and to -store them in different places. For example, if you would like -to store new tasks under a heading @samp{Tasks} in file @file{TODO.org}, and -journal entries in a date tree in @file{journal.org} you could -use: - -@smallexample -(setq org-capture-templates - '(("t" "Todo" entry (file+headline "~/org/gtd.org" "Tasks") - "* TODO %?\n %i\n %a") - ("j" "Journal" entry (file+datetree "~/org/journal.org") - "* %?\nEntered on %U\n %i\n %a"))) -@end smallexample - -@noindent -In these entries, the first string is the key to reach the -template, the second is a short description. Then follows the type of the -entry and a definition of the target location for storing the note. Finally, -the template itself, a string with %-escapes to fill in information based on -time and context. - -When you call @kbd{M-x org-capture}, Org will prompt for a key to select the -template (if you have more than one template) and then prepare the buffer like -@smallexample -* TODO - [[file:@var{link to where you were when initiating capture}]] -@end smallexample - -@noindent -During expansion of the template, special @kbd{%}-escapes@footnote{If you -need one of these sequences literally, escape the @kbd{%} with a backslash.} -allow dynamic insertion of content. Here is a small selection of the -possibilities, consult the manual for more. -@smallexample -%a @r{annotation, normally the link created with @code{org-store-link}} -%i @r{initial content, the region when capture is called with C-u.} -%t, %T @r{timestamp, date only, or date and time} -%u, %U @r{like above, but inactive timestamps} -@end smallexample - -@node Refile and copy, Archiving, Capture, Capture - Refile - Archive -@section Refile and copy - -When reviewing the captured data, you may want to refile or copy some of the -entries into a different list, for example into a project. Cutting, finding -the right location, and then pasting the note is cumbersome. To simplify -this process, use the following commands: - -@table @kbd -@item C-c M-w -Copy the entry or region at point. This command behaves like -@code{org-refile}, except that the original note will not be deleted. -@item C-c C-w -Refile the entry or region at point. This command offers possible locations -for refiling the entry and lets you select one with completion. The item (or -all items in the region) is filed below the target heading as a 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. -@item C-u C-c C-w -Use the refile interface to jump to a heading. -@item C-u C-u C-c C-w -Jump to the location where @code{org-refile} last moved a tree to. -@end table - -@node Archiving, , Refile and copy, Capture - Refile - Archive -@section Archiving - -When a project represented by a (sub)tree is finished, you may want -to move the tree out of the way and to stop it from contributing to the -agenda. Archiving is important to keep your working files compact and global -searches like the construction of agenda views fast. -The most common archiving action is to move a project tree to another file, -the archive file. - -@table @kbd -@item C-c C-x C-a -Archive the current entry using @code{org-archive-default-command}. -@item C-c C-x C-s@ @r{or short} @ C-c $ -Archive the subtree starting at the cursor position to the location -given by @code{org-archive-location}. -@end table - -The default archive location is a file in the same directory as the -current file, with the name derived by appending @file{_archive} to the -current file name. For information and examples on how to change this, -see the documentation string of the variable -@code{org-archive-location}. There is also an in-buffer option for -setting this variable, for example - -@smallexample -#+ARCHIVE: %s_done:: -@end smallexample - -@seealso{ -@uref{https://orgmode.org/manual/Capture-_002d-Refile-_002d-Archive.html#Capture-_002d-Refile-_002d-Archive, -Chapter 9 of the manual}@* -@uref{https://orgmode.org/worg/org-tutorials/org-protocol-custom-handler.html, -Sebastian Rose's tutorial for capturing from a web browser}}@uref{}@* - -@node Agenda Views, Markup, Capture - Refile - Archive, Top -@chapter Agenda Views - -Due to the way Org works, TODO items, time-stamped items, and tagged -headlines can be scattered throughout a file or even a number of files. To -get an overview of open action items, or of events that are important for a -particular date, this information must be collected, sorted and displayed in -an organized way. There are several different views, see below. - -The extracted information is displayed in a special @emph{agenda buffer}. -This buffer is read-only, but provides commands to visit the corresponding -locations in the original Org files, and even to edit these files remotely. -Remote editing from the agenda buffer means, for example, that you can -change the dates of deadlines and appointments from the agenda buffer. -The commands available in the Agenda buffer are listed in @ref{Agenda -commands}. - -@menu -* Agenda files:: Files being searched for agenda information -* Agenda dispatcher:: Keyboard access to agenda views -* Built-in agenda views:: What is available out of the box? -* Agenda commands:: Remote editing of Org trees -* Custom agenda views:: Defining special searches and views -@end menu - -@node Agenda files, Agenda dispatcher, Agenda Views, Agenda Views -@section Agenda files - -The information to be shown is normally collected from all @emph{agenda -files}, the files listed in the variable -@code{org-agenda-files}. - -@table @kbd -@item C-c [ -Add current file to the list of agenda files. The file is added to -the front of the list. If it was already in the list, it is moved to -the front. With a prefix argument, file is added/moved to the end. -@item C-c ] -Remove current file from the list of agenda files. -@item C-, -Cycle through agenda file list, visiting one file after the other. -@end table - -@node Agenda dispatcher, Built-in agenda views, Agenda files, Agenda Views -@section The agenda dispatcher -The views are created through a dispatcher, which should be bound to a -global key---for example @kbd{C-c a} (@pxref{Installation}). After -pressing @kbd{C-c a}, an additional letter is required to execute a -command: -@table @kbd -@item a -The calendar-like agenda (@pxref{Weekly/daily agenda}). -@item t @r{/} T -A list of all TODO items (@pxref{Global TODO list}). -@item m @r{/} M -A list of headlines matching a TAGS expression (@pxref{Matching -tags and properties}). -@item s -A list of entries selected by a boolean expression of keywords -and/or regular expressions that must or must not occur in the entry. -@end table - -@node Built-in agenda views, Agenda commands, Agenda dispatcher, Agenda Views -@section The built-in agenda views - -@menu -* Weekly/daily agenda:: The calendar page with current tasks -* Global TODO list:: All unfinished action items -* Matching tags and properties:: Structured information with fine-tuned search -* Search view:: Find entries by searching for text -@end menu - -@node Weekly/daily agenda, Global TODO list, Built-in agenda views, Built-in agenda views -@subsection The weekly/daily agenda - -The purpose of the weekly/daily @emph{agenda} is to act like a page of a -paper agenda, showing all the tasks for the current week or day. - -@table @kbd -@item C-c a a -Compile an agenda for the current week from a list of Org files. The agenda -shows the entries for each day. -@end table - -Emacs contains the calendar and diary by Edward M. Reingold. Org-mode -understands the syntax of the diary and allows you to use diary sexp entries -directly in Org files: - -@smallexample -* Birthdays and similar stuff -#+CATEGORY: Holiday -%%(org-calendar-holiday) ; special function for holiday names -#+CATEGORY: Ann -%%(diary-anniversary 5 14 1956)@footnote{Note that the order of the arguments (month, day, year) depends on the setting of @code{calendar-date-style}.} Arthur Dent is %d years old -%%(diary-anniversary 10 2 1869) Mahatma Gandhi would be %d years old -@end smallexample - -Org can interact with Emacs appointments notification facility. To add all -the appointments of your agenda files, use the command -@code{org-agenda-to-appt}. See the docstring for details. - -@node Global TODO list, Matching tags and properties, Weekly/daily agenda, Built-in agenda views -@subsection The global TODO list - -The global TODO list contains all unfinished TODO items formatted and -collected into a single place. Remote editing of TODO items lets you -can change the state of a TODO entry with a single key press. The commands -available in the TODO list are described in @ref{Agenda commands}. - -@table @kbd -@item C-c a t -Show the global TODO list. This collects the TODO items from all -agenda files (@pxref{Agenda Views}) into a single buffer. -@item C-c a T -Like the above, but allows selection of a specific TODO keyword. -@end table - -@node Matching tags and properties, Search view, Global TODO list, Built-in agenda views -@subsection Matching tags and properties - -If headlines in the agenda files are marked with @emph{tags} (@pxref{Tags}), -or have properties (@pxref{Properties}), you can select headlines -based on this metadata and collect them into an agenda buffer. The match -syntax described here also applies when creating sparse trees with @kbd{C-c / -m}. The commands available in the tags list are described in @ref{Agenda -commands}. - -@table @kbd -@item C-c a m -Produce a list of all headlines that match a given set of tags. The -command prompts for a selection criterion, which is a boolean logic -expression with tags, like @samp{+work+urgent-withboss} or -@samp{work|home} (@pxref{Tags}). If you often need a specific search, -define a custom command for it (@pxref{Agenda dispatcher}). -@item C-c a M -Like @kbd{C-c a m}, but only select headlines that are also TODO items. -@end table - -@subsubheading Match syntax - -A search string can use Boolean operators @samp{&} for AND and @samp{|} for -OR. @samp{&} binds more strongly than @samp{|}. Parentheses are currently -not implemented. Each element in the search is either a tag, a regular -expression matching tags, or an expression like @code{PROPERTY OPERATOR -VALUE} with a comparison operator, accessing a property value. Each element -may be preceded by @samp{-}, to select against it, and @samp{+} is syntactic -sugar for positive selection. The AND operator @samp{&} is optional when -@samp{+} or @samp{-} is present. Here are some examples, using only tags. - -@table @samp -@item +work-boss -Select headlines tagged @samp{:work:}, but discard those also tagged -@samp{:boss:}. -@item work|laptop -Selects lines tagged @samp{:work:} or @samp{:laptop:}. -@item work|laptop+night -Like before, but require the @samp{:laptop:} lines to be tagged also -@samp{:night:}. -@end table - -You may also test for properties at the same -time as matching tags, see the manual for more information. - -@node Search view, , Matching tags and properties, Built-in agenda views -@subsection Search view - -This agenda view is a general text search facility for Org mode entries. -It is particularly useful to find notes. - -@table @kbd -@item C-c a s -This is a special search that lets you select entries by matching a substring -or specific words using a boolean logic. -@end table -For example, the search string @samp{computer equipment} will find entries -that contain @samp{computer equipment} as a substring. -Search view can also search for specific keywords in the entry, using Boolean -logic. The search string @samp{+computer +wifi -ethernet -@{8\.11[bg]@}} -will search for note entries that contain the keywords @code{computer} -and @code{wifi}, but not the keyword @code{ethernet}, and which are also -not matched by the regular expression @code{8\.11[bg]}, meaning to -exclude both 8.11b and 8.11g. - -Note that in addition to the agenda files, this command will also search -the files listed in @code{org-agenda-text-search-extra-files}. - -@node Agenda commands, Custom agenda views, Built-in agenda views, Agenda Views -@section Commands in the agenda buffer - -Entries in the agenda buffer are linked back to the Org file or diary -file where they originate. Commands are provided to show and jump to the -original entry location, and to edit the Org files ``remotely'' from -the agenda buffer. This is just a selection of the many commands, explore -the @code{Agenda} menu and the manual for a complete list. - -@table @kbd -@tsubheading{Motion} -@item n -Next line (same as @key{up} and @kbd{C-p}). -@item p -Previous line (same as @key{down} and @kbd{C-n}). -@tsubheading{View/Go to Org file} -@item mouse-3 -@itemx @key{SPC} -Display the original location of the item in another window. -With prefix arg, make sure that the entire entry is made visible in the -outline, not only the heading. -@c -@item @key{TAB} -Go to the original location of the item in another window. Under Emacs -22, @kbd{mouse-1} will also work for this. -@c -@item @key{RET} -Go to the original location of the item and delete other windows. -@c - -@tsubheading{Change display} -@item o -Delete other windows. -@c -@item d @r{/} w -Switch to day/week view. -@c -@item f @r{and} b -Go forward/backward in time to display the following -@code{org-agenda-current-span} days. For example, if the display covers a -week, switch to the following/previous week. -@c -@item . -Go to today. -@c -@item j -Prompt for a date and go there. -@c -@item v l @ @r{or short} @ l -Toggle Logbook mode. In Logbook mode, entries that were 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. When called with a @kbd{C-u} -prefix, show all possible logbook entries, including state changes. -@c -@item r @r{or} g -Recreate the agenda buffer, to reflect the changes. -@item s -Save all Org buffers in the current Emacs session, and also the locations of -IDs. - -@tsubheading{Secondary filtering and query editing} - -@item / -Filter the current agenda view with respect to a tag. You are prompted for a -letter to select a tag. Press @samp{-} first to select against the tag. - -@item \ -Narrow the current agenda filter by an additional condition. - -@tsubheading{Remote editing (see the manual for many more commands)} - -@item 0--9 -Digit argument. -@c -@item t -Change the TODO state of the item, in the agenda and in the -org file. -@c -@item C-k -Delete the current agenda item along with the entire subtree belonging -to it in the original Org file. -@c -@item C-c C-w -Refile the entry at point. -@c -@item C-c C-x C-a @ @r{or short} @ a -Archive the subtree corresponding to the entry at point using the default -archiving command set in @code{org-archive-default-command}. -@c -@item C-c C-x C-s @ @r{or short} @ $ -Archive the subtree corresponding to the current headline. -@c -@item C-c C-s -Schedule this item, with prefix arg remove the scheduling timestamp -@c -@item C-c C-d -Set a deadline for this item, with prefix arg remove the deadline. -@c -@item S-@key{right} @r{and} S-@key{left} -Change the timestamp associated with the current line by one day. -@c -@item I -Start the clock on the current item. -@c -@item O / X -Stop/cancel the previously started clock. - -@item J -Jump to the running clock in another window. -@end table - -@node Custom agenda views, , Agenda commands, Agenda Views -@section Custom agenda views - -The main application of custom searches is the definition of keyboard -shortcuts for frequently used searches, either creating an agenda -buffer, or a sparse tree (the latter covering of course only the current -buffer). -Custom commands are configured in the variable -@code{org-agenda-custom-commands}. You can customize this variable, for -example by pressing @kbd{C-c a C}. You can also directly set it with -Emacs Lisp in @file{.emacs}. The following example contains all valid -search types: - -@smalllisp -@group -(setq org-agenda-custom-commands - '(("w" todo "WAITING") - ("u" tags "+boss-urgent") - ("v" tags-todo "+boss-urgent"))) -@end group -@end smalllisp - -@noindent -The initial string in each entry defines the keys you have to press after the -dispatcher command @kbd{C-c a} in order to access the command. Usually this -will be just a single character. The second parameter is the search type, -followed by the string or regular expression to be used for the matching. -The example above will therefore define: - -@table @kbd -@item C-c a w -as a global search for TODO entries with @samp{WAITING} as the TODO -keyword -@item C-c a u -as a global tags search for headlines marked @samp{:boss:} but not -@samp{:urgent:} -@item C-c a v -as the same search as @kbd{C-c a u}, but limiting the search to -headlines that are also TODO items -@end table - -@seealso{ -@uref{https://orgmode.org/manual/Agenda-views.html#Agenda-views, Chapter 10 of -the manual}@* -@uref{https://orgmode.org/worg/org-tutorials/org-custom-agenda-commands.html, -Mat Lundin's tutorial about custom agenda commands}@* -@uref{http://www.newartisans.com/2007/08/using-org-mode-as-a-day-planner.html, -John Wiegley's setup}} - -@node Markup, Exporting, Agenda Views, Top -@chapter Markup for rich export - -When exporting Org-mode documents, the exporter tries to reflect the -structure of the document as accurately as possible in the backend. Since -export targets like HTML, @LaTeX{}, or DocBook allow much richer formatting, -Org mode has rules on how to prepare text for rich export. This section -summarizes the markup rules used in an Org-mode buffer. - -@menu -* Structural markup elements:: The basic structure as seen by the exporter -* Images and tables:: Images, tables and caption mechanism -* Literal examples:: Source code examples with special formatting -* Include files:: Include additional files into a document -* Embedded @LaTeX{}:: @LaTeX{} can be freely used inside Org documents -@end menu - -@node Structural markup elements, Images and tables, Markup, Markup -@section Structural markup elements - -@menu -* Document title:: Where the title is taken from -* Headings and sections:: The document structure as seen by the exporter -* Table of contents:: The if and where of the table of contents -* Paragraphs:: Paragraphs -* Emphasis and monospace:: Bold, italic, etc. -* Comment lines:: What will *not* be exported -@end menu - -@node Document title, Headings and sections, Structural markup elements, Structural markup elements -@subheading Document title - -@noindent -The title of the exported document is taken from the special line - -@smallexample -#+TITLE: This is the title of the document -@end smallexample - -@node Headings and sections, Table of contents, Document title, Structural markup elements -@subheading Headings and sections - -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-export-headline-levels}, or on a -per-file basis with a line - -@smallexample -#+OPTIONS: H:4 -@end smallexample - -@node Table of contents, Paragraphs, Headings and sections, Structural markup elements -@subheading Table of contents - -The table of contents is normally inserted directly before the first headline -of the file. - -@smallexample -#+OPTIONS: toc:2 (only to two levels in TOC) -#+OPTIONS: toc:nil (no TOC at all) -@end smallexample - -@node Paragraphs, Emphasis and monospace, Table of contents, Structural markup elements -@subheading Paragraphs, line breaks, and quoting - -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. - -@smallexample -#+BEGIN_VERSE - Great clouds overhead - Tiny black birds rise and fall - Snow covers Emacs - - -- AlexSchroeder -#+END_VERSE -@end smallexample - -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: - -@smallexample -#+BEGIN_QUOTE -Everything should be made as simple as possible, -but not any simpler -- Albert Einstein -#+END_QUOTE -@end smallexample - -If you would like to center some text, do it like this: -@smallexample -#+BEGIN_CENTER -Everything should be made as simple as possible, \\ -but not any simpler -#+END_CENTER -@end smallexample - -@node Emphasis and monospace, Comment lines, Paragraphs, Structural markup elements -@subheading Emphasis and monospace - -You can make words @b{*bold*}, @i{/italic/}, _underlined_, @code{=verbatim=} -and @code{~code~}, 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. To insert a horizontal rules, use a line consisting of -only dashes, and at least 5 of them. - -@node Comment lines, , Emphasis and monospace, Structural markup elements -@subheading Comment lines - -Lines starting with zero or more whitespace characters followed by @samp{#} -and a whitespace are treated as comments and, as such, are not exported. - -Likewise, regions surrounded by @samp{#+BEGIN_COMMENT} -... @samp{#+END_COMMENT} are not exported. - -Finally, a @samp{COMMENT} keyword at the beginning of an entry, but after any -other keyword or priority cookie, comments out the entire subtree. The -command below helps changing the comment status of a headline. - -@table @kbd -@item C-c ; -Toggle the COMMENT keyword at the beginning of an entry. -@end table - -@node Images and tables, Literal examples, Structural markup elements, Markup -@section Images and Tables - -For Org mode tables, the lines before the first horizontal separator line -will become table header lines. You can use the following lines somewhere -before the table to assign a caption and a label for cross references, and in -the text you can refer to the object with @code{[[tab:basic-data]]}: - -@smallexample -#+CAPTION: This is the caption for the next table (or link) -#+NAME: tbl:basic-data - | ... | ...| - |-----|----| -@end smallexample - -Some backends allow you to directly include images into the exported -document. Org does this, if a link to an image files does not have -a description part, for example @code{[[./img/a.jpg]]}. If you wish to -define a caption for the image and maybe a label for internal cross -references, you sure that the link is on a line by itself precede it with: - -@smallexample -#+CAPTION: This is the caption for the next figure link (or table) -#+NAME: fig:SED-HR4049 -[[./img/a.jpg]] -@end smallexample - -The same caption mechanism applies to other structures than images and tables -(e.g., @LaTeX{} equations, source code blocks), provided the chosen export -back-end supports them. - -@node Literal examples, Include files, Images and tables, Markup -@section Literal examples - -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. - -@smallexample -#+BEGIN_EXAMPLE -Some example from a text file. -#+END_EXAMPLE -@end smallexample - -For simplicity when using small examples, you can also start the example -lines with a colon followed by a space. There may also be additional -whitespace before the colon: - -@smallexample -Here is an example - : Some example from a text file. -@end smallexample - -For source code from a programming language, or any other text -that can be marked up by font-lock in Emacs, you can ask for it to -look like the fontified Emacs buffer - -@smallexample -#+BEGIN_SRC emacs-lisp -(defun org-xor (a b) - "Exclusive or." - (if a (not b) b)) -#+END_SRC -@end smallexample - -To edit the example in a special buffer supporting this language, use -@kbd{C-c '} to both enter and leave the editing buffer. - -@node Include files, Embedded @LaTeX{}, Literal examples, Markup -@section Include files - -During export, you can include the content of another file. For example, to -include your @file{.emacs} file, you could use: - -@smallexample -#+INCLUDE: "~/.emacs" src emacs-lisp -@end smallexample -@noindent -The optional second and third parameter are the markup (i.e., @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. File-links -will be interpreted as well: -@smallexample -#+INCLUDE: "./otherfile.org::#my_custom_id" :only-contents t -@end smallexample -@noindent -@kbd{C-c '} will visit the included file. - -@node Embedded @LaTeX{}, , Include files, Markup -@section Embedded @LaTeX{} - -For scientific notes which need to be able to contain mathematical symbols -and the occasional formula, Org-mode supports embedding @LaTeX{} code into -its files. You can directly use TeX-like syntax for special symbols, enter -formulas and entire @LaTeX{} environments. - -@smallexample -Angles are written as Greek letters \alpha, \beta and \gamma. The mass if -the sun is M_sun = 1.989 x 10^30 kg. The radius of the sun is R_@{sun@} = -6.96 x 10^8 m. If $a^2=b$ and $b=2$, then the solution must be either -$a=+\sqrt@{2@}$ or $a=-\sqrt@{2@}$. - -\begin@{equation@} -x=\sqrt@{b@} -\end@{equation@} -@end smallexample -@noindent -With -@uref{https://orgmode.org/manual/LaTeX-fragments.html#LaTeX-fragments,special -setup}, @LaTeX{} snippets will be included as images when exporting to HTML. - -@seealso{ -@uref{https://orgmode.org/manual/Markup.html#Markup, Chapter 11 of the manual}} - -@node Exporting, Publishing, Markup, Top -@chapter Exporting - -Org-mode documents can be exported into a variety of other formats: ASCII -export for inclusion into emails, HTML to publish on the web, @LaTeX{}/PDF -for beautiful printed documents and DocBook to enter the world of many other -formats using DocBook tools. There is also export to iCalendar format so -that planning information can be incorporated into desktop calendars. - -@menu -* Export options:: Per-file export settings -* The export dispatcher:: How to access exporter commands -* ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding -* HTML export:: Exporting to HTML -* @LaTeX{} and PDF export:: Exporting to @LaTeX{}, and processing to PDF -* iCalendar export:: Exporting to iCalendar -@end menu - -@node Export options, The export dispatcher, Exporting, Exporting -@section Export options - -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 #}. - -@table @kbd -@item C-c C-e # -Insert template with export options, see example below. -@end table - -@smallexample -#+TITLE: the title to be shown -#+AUTHOR: the author (default taken from @code{user-full-name}) -#+DATE: a date, fixed, or an Org timestamp -#+EMAIL: his/her email address (default from @code{user-mail-address}) -#+LANGUAGE: language, e.g.@: @samp{en} (@code{org-export-default-language}) -#+OPTIONS: H:2 num:t toc:t \n:nil ::t |:t ^:t f:t tex:t ... -@end smallexample - -@node The export dispatcher, ASCII/Latin-1/UTF-8 export, Export options, Exporting -@section The export dispatcher - -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 a region is active, it will be -exported instead. - -@table @kbd -@item C-c C-e -Dispatcher for export and publishing commands. -@end table - -@node ASCII/Latin-1/UTF-8 export, HTML export, The export dispatcher, Exporting -@section ASCII/Latin-1/UTF-8 export - -ASCII export produces a simple and very readable version of an Org-mode -file, containing only plain ASCII. Latin-1 and UTF-8 export augment the file -with special characters and symbols available in these encodings. - -@table @kbd -@item C-c C-e t a @ @ @r{and} @ @ C-c C-e t A -Export as ASCII file or temporary buffer. -@item C-c C-e t n @ @ @r{and} @ @ C-c C-e t N -Like the above commands, but use Latin-1 encoding. -@item C-c C-e t u @ @ @r{and} @ @ C-c C-e t U -Like the above commands, but use UTF-8 encoding. -@end table - -@node HTML export, @LaTeX{} and PDF export, ASCII/Latin-1/UTF-8 export, Exporting -@section HTML export - -@table @kbd -@item C-c C-e h h -Export as HTML file @file{myfile.html}. -@item C-c C-e h o -Export as HTML file and immediately open it with a browser. -@end table - -To insert HTML that should be copied verbatim to -the exported file use either - -@smallexample -#+HTML: Literal HTML code for export -@end smallexample -@noindent -or -@smallexample -#+BEGIN_EXPORT html -All lines between these markers are exported literally -#+END_HTML -@end smallexample - -@node @LaTeX{} and PDF export, iCalendar export, HTML export, Exporting -@section @LaTeX{} and PDF export - -@table @kbd -@item C-c C-e l l -Export as @LaTeX{} file @file{myfile.tex}. -@item C-c C-e l p -Export as @LaTeX{} and then process to PDF. -@item C-c C-e l o -Export as @LaTeX{} and then process to PDF, then open the resulting PDF file. -@end table - -By default, the @LaTeX{} output uses the class @code{article}. You can -change this by adding an option like @code{#+LATEX_CLASS: myclass} in your -file. The class must be listed in @code{org-latex-classes}. - -Embedded @LaTeX{} as described in @ref{Embedded @LaTeX{}}, will be correctly -inserted into the @LaTeX{} file. Similarly to the HTML exporter, you can use -@code{#+LATEX:} and @code{#+BEGIN_EXPORT latex ... #+END_EXPORT} construct to -add verbatim @LaTeX{} code. - -@node iCalendar export, , @LaTeX{} and PDF export, Exporting -@section iCalendar export - -@table @kbd -@item C-c C-e c f -Create iCalendar entries for the current file in a @file{.ics} file. -@item C-c C-e c c -Create a single large iCalendar file from all files in -@code{org-agenda-files} and write it to the file given by -@code{org-icalendar-combined-agenda-file}. -@end table - -@seealso{ -@uref{https://orgmode.org/manual/Exporting.html#Exporting, Chapter 12 of the manual}@* -@uref{https://orgmode.org/worg/org-tutorials/images-and-xhtml-export.html, -Sebastian Rose's image handling tutorial}@* -@uref{https://orgmode.org/worg/org-tutorials/org-latex-export.html, Thomas -Dye's LaTeX export tutorial} -@uref{https://orgmode.org/worg/exporters/beamer/tutorial.html, Eric -Fraga's BEAMER presentation tutorial}} - -@node Publishing, Working With Source Code, Exporting, Top -@chapter Publishing - -Org includes a publishing management system that allows you to configure -automatic HTML conversion of @emph{projects} composed of interlinked org -files. You can also configure Org to automatically upload your exported HTML -pages and related attachments, such as images and source code files, to a web -server. For detailed instructions about setup, see the manual. - -Here is an example: - -@smalllisp -(setq org-publish-project-alist - '(("org" - :base-directory "~/org/" - :publishing-directory "~/public_html" - :section-numbers nil - :table-of-contents nil - :style "<link rel=\"stylesheet\" - href=\"../other/mystyle.css\" - type=\"text/css\"/>"))) -@end smalllisp - -@table @kbd -@item C-c C-e P x -Prompt for a specific project and publish all files that belong to it. -@item C-c C-e P p -Publish the project containing the current file. -@item C-c C-e P f -Publish only the current file. -@item C-c C-e P a -Publish every project. -@end table - -Org uses timestamps to track when a file has changed. The above functions -normally only publish changed files. You can override this and force -publishing of all files by giving a prefix argument to any of the commands -above. - -@seealso{ -@uref{https://orgmode.org/manual/Publishing.html#Publishing, Chapter 13 of the -manual}@* -@uref{https://orgmode.org/worg/org-tutorials/org-publish-html-tutorial.html, -Sebastian Rose's publishing tutorial}@* -@uref{https://orgmode.org/worg/org-tutorials/org-jekyll.html, Ian Barton's -Jekyll/blogging setup}} - -@node Working With Source Code, Miscellaneous, Publishing, Top -@chapter Working with source code -Org-mode provides a number of features for working with source code, -including editing of code blocks in their native major-mode, evaluation of -code blocks, tangling of code blocks, and exporting code blocks and their -results in several formats. - -@subheading Structure of Code Blocks -The structure of code blocks is as follows: - -@example -#+NAME: <name> -#+BEGIN_SRC <language> <switches> <header arguments> - <body> -#+END_SRC -@end example - -Where @code{<name>} is a string used to name the code block, -@code{<language>} specifies the language of the code block -(e.g.@: @code{emacs-lisp}, @code{shell}, @code{R}, @code{python}, etc...), -@code{<switches>} can be used to control export of the code block, -@code{<header arguments>} can be used to control many aspects of code block -behavior as demonstrated below, and @code{<body>} contains the actual source -code. - -@subheading Editing source code -Use @kbd{C-c '} to edit the current code block. This brings up a language -major-mode edit buffer containing the body of the code block. Saving this -buffer will write the new contents back to the Org buffer. Use @kbd{C-c '} -again to exit the edit buffer. - -@subheading Evaluating code blocks -Use @kbd{C-c C-c} to evaluate the current code block and insert its results -in the Org-mode buffer. By default, evaluation is only turned on for -@code{emacs-lisp} code blocks, however support exists for evaluating blocks -in many languages. For a complete list of supported languages see the -manual. The following shows a code block and its results. - -@example -#+BEGIN_SRC emacs-lisp - (+ 1 2 3 4) -#+END_SRC - -#+RESULTS: -: 10 -@end example - -@subheading Extracting source code -Use @kbd{C-c C-v t} to create pure source code files by extracting code from -source blocks in the current buffer. This is referred to as ``tangling''---a -term adopted from the literate programming community. During ``tangling'' of -code blocks their bodies are expanded using @code{org-babel-expand-src-block} -which can expand both variable and ``noweb'' style references. In order to -tangle a code block it must have a @code{:tangle} header argument, see the -manual for details. - -@subheading Library of Babel -Use @kbd{C-c C-v l} to load the code blocks from an Org-mode files into the -``Library of Babel'', these blocks can then be evaluated from any Org-mode -buffer. A collection of generally useful code blocks is accessible through -Org-mode’s community-driven documentation on -@uref{https://orgmode.org/worg/library-of-babel.html,Worg}. - -@subheading Header Arguments -Many aspects of the evaluation and export of code blocks are controlled -through header arguments. These can be specified globally, at the file -level, at the outline subtree level, and at the individual code block level. -The following describes some of the header arguments. -@table @code -@item :var -The @code{:var} header argument is used to pass arguments to code blocks. -The values passed to arguments can be literal values, values from org-mode -tables and literal example blocks, or the results of other named code blocks. -@item :results -The @code{:results} header argument controls the @emph{collection}, -@emph{type}, and @emph{handling} of code block results. Values of -@code{output} or @code{value} (the default) specify how results are collected -from a code block's evaluation. Values of @code{vector}, @code{scalar} -@code{file} @code{raw} @code{html} @code{latex} and @code{code} specify the -type of the results of the code block which dictates how they will be -incorporated into the Org-mode buffer. Values of @code{silent}, -@code{replace}, @code{prepend}, and @code{append} specify handling of code -block results, specifically if and how the results should be inserted into -the Org-mode buffer. -@item :session -A header argument of @code{:session} will cause the code block to be -evaluated in a persistent interactive inferior process in Emacs. This allows -for persisting state between code block evaluations, and for manual -inspection of the results of evaluation. -@item :exports -Any combination of the @emph{code} or the @emph{results} of a block can be -retained on export, this is specified by setting the @code{:results} header -argument to @code{code} @code{results} @code{none} or @code{both}. -@item :tangle -A header argument of @code{:tangle yes} will cause a code block's contents to -be tangled to a file named after the filename of the Org-mode buffer. An -alternate file name can be specified with @code{:tangle filename}. -@item :cache -A header argument of @code{:cache yes} will cause associate a hash of the -expanded code block with the results, ensuring that code blocks are only -re-run when their inputs have changed. -@item :noweb -A header argument of @code{:noweb yes} will expand ``noweb'' style references -on evaluation and tangling. -@item :file -Code blocks which output results to files (e.g.@: graphs, diagrams and figures) -can accept a @code{:file filename} header argument in which case the results -are saved to the named file, and a link to the file is inserted into the -Org-mode buffer. -@end table - -@seealso{ -@uref{https://orgmode.org/manual/Literal-examples.html#Literal-examples, -Chapter 11 and section 5 of the manual}@* -@uref{https://orgmode.org/worg/org-contrib/babel/, -The Babel site on Worg}} - -@node Miscellaneous, GNU Free Documentation License, Working With Source Code, Top -@chapter Miscellaneous - -@menu -* Completion:: M-TAB knows what you need -* Clean view:: Getting rid of leading stars in the outline -* MobileOrg:: Org-mode on the iPhone -@end menu - -@node Completion, Clean view, Miscellaneous, Miscellaneous -@section Completion - -Org supports in-buffer completion with @kbd{M-@key{TAB}}. This type of -completion does not make use of the minibuffer. You simply type a few -letters into the buffer and use the key to complete text right there. For -example, this command will complete @TeX{} symbols after @samp{\}, TODO -keywords at the beginning of a headline, and tags after @samp{:} in a -headline. - -@node Clean view, MobileOrg, Completion, Miscellaneous -@section A cleaner outline view - -Some people find it noisy and distracting that the Org headlines start with a -potentially large number of stars, and that text below the headlines is not -indented. While this is no problem when writing a @emph{book-like} document -where the outline headings are really section headings, in a more -@emph{list-oriented} outline, indented structure is a lot cleaner: - -@smallexample -@group -* 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 -@end group -@end smallexample - -@noindent -This kind of view can be achieved dynamically at display time using -@code{org-indent-mode}, which will prepend intangible space to each line. -You can turn on @code{org-indent-mode} for all files by customizing the -variable @code{org-startup-indented}, or you can turn it on for individual -files using - -@smallexample -#+STARTUP: indent -@end smallexample - -If you want a similar effect in earlier version of Emacs and/or Org, or if -you want the indentation to be hard space characters so that the plain text -file looks as similar as possible to the Emacs display, Org supports you by -helping to indent (with @key{TAB}) text below each headline, by hiding -leading stars, and by only using levels 1, 3, etc to get two characters -indentation for each level. To get this support in a file, use - -@smallexample -#+STARTUP: hidestars odd -@end smallexample - -@node MobileOrg, , Clean view, Miscellaneous -@section MobileOrg - -@i{MobileOrg} is the name of the mobile companion app for Org mode, currently -available for iOS and for Android. @i{MobileOrg} offers offline viewing and -capture support for an Org mode system rooted on a ``real'' computer. It -does also allow you to record changes to existing entries. - -The @uref{http://mobileorg.ncogni.to/, iOS implementation} for the -@i{iPhone/iPod Touch/iPad} series of devices, was developed by Richard -Moreland. Android users should check out -@uref{http://wiki.github.com/matburt/mobileorg-android/, MobileOrg Android} -by Matt Jones. The two implementations are not identical but offer similar -features. - -@seealso{ -@uref{https://orgmode.org/manual/Miscellaneous.html#Miscellaneous, Chapter 15 -of the manual}@* -@uref{https://orgmode.org/manual/MobileOrg.html#MobileOrg, Appendix B of the -manual}@* -@uref{https://orgmode.org/orgcard.pdf,Key reference card}} - - -@node GNU Free Documentation License, , Miscellaneous, Top -@appendix GNU Free Documentation License -@include doclicense.texi - - -@bye - -@c Local variables: -@c fill-column: 77 -@c End: - - -@c LocalWords: webdavhost pre |