1 #+title: Org-mode Frequently Asked Questions
2 #+email: mdl AT imapmail DOT org
6 #+setupfile: macros.setupfile
8 [[file:index.org][{Back to Worg's index}]]
10 * Is my question already a Frequently Asked Questions ?
12 You can find answers by asking on the mailing list, but people will
13 probably direct you here, so it is safer to start by checking this
18 :CUSTOM_ID: What-is-org-mode
21 ** Can Org-mode do "x"? Does org have "x" feature?
23 :CUSTOM_ID: can-org-do-x
26 In its default setup, Org-mode offers a simple outlining and task
27 management environment. But it also has a huge number of features and
28 settings "under the hood." Advanced users have configured Org-mode for
29 almost every conceivable use scenario.
31 Org-mode has a very active community and rich and extensive
32 documentation. Before emailing the mailing list to ask whether
33 Org-mode has a particular feature or setting, please consult the
36 - Read/search the manual.
38 - https://orgmode.org/manual/index.html
40 - Make sure to check out the following indexes:
42 - [[https://orgmode.org/manual/Main-Index.html#Main-Index][Main Index]]
43 - [[https://orgmode.org/manual/Key-Index.html#Key-Index][Key Index]]
44 - [[https://orgmode.org/manual/Variable-Index.html#Variable-Index][Variable Index]]
46 - The manual is also easily available from within emacs.
48 To read the manual within emacs, you can evaluate =(info
49 "(org)")= within emacs---i.e., type =C-x C-e= after the closing
50 paragraph of the info expression above.
52 You can also type =M-x info= and navigate to "Org Mode".
54 You can search the entire manual by typing ~C-s term~. Keep
55 pressing ~C-s~ to cycle through the results
57 - Search the mailing list archives at [[http://lists.gnu.org/archive/html/emacs-orgmode/][lists.gnu.org]] or
58 [[https://orgmode.org/list/][orgmode.org/list]].
60 There is a good chance that the feature you are looking for has
61 already been discussed (most likely several times).
63 - Check for features from within emacs.
65 - Emacs has a wonderful built-in help system.
67 - You can browse (and change) most customization options by typing
70 - You can check for a feature by typing =M-x apropos [RET] [word]= or
71 =C-h a word=. This will search for all functions and variables
72 matching the term (or regexp) you enter.
74 - You can browse (and search for) org functions, variables, and
75 faces by using =M-x describe-variable= (=C-h v=), =M-x
76 describe-function= (=C-h f=), or =M-x describe-face=.
78 After invoking one of these commands, simply type =org-[TAB]= to
79 see a full list of relevant functions or variables or faces. You
80 can then drill down further: e.g., =org-export-[TAB]= for export
83 - Checkout the [[file:org-tutorials/index.org][tutorials on Worg]].
85 Several of these tutorials discuss advanced features (e.g.,
86 searching, custom agenda commands, tables, publishing) of Org-mode
89 There are many other resources on Worg as well:
91 - [[https://orgmode.org/worg/org-configs/index.html][Org Customization]] :: Includes a guide for beginners.
93 - [[https://orgmode.org/worg/org-hacks.html][Org Hacks]] :: User-generated modifications and add-ons.
95 - [[https://orgmode.org/worg/org-glossary.html][Org Glossary]] :: An explanation of basic Org-mode terms and
98 ** Can I implement a GTD workflow with Org-mode?
100 :CUSTOM_ID: GTD-workflow-with-Org-mode
103 #+index: GTD!Workflow
105 Yes, you can. Check for discussions and pointers [[https://orgmode.org/worg/org-gtd-etc.html][here]].
107 ** What is the difference between Org and TaskPaper?
109 :CUSTOM_ID: Org-and-TaskPaper
114 There is really no difference. Org is as /simple/ as [[http://hogbaysoftware.com/products/taskpaper][TaskPaper]]. It
115 is just that, when using Org within Emacs, it lets you do many things
116 that you wouldn't be able to do with TaskPaper. Yes, TaskPaper is
117 fiddle-proof and people using Emacs tends to like fiddling (which is
118 orthogonal to the idea of using todo-lists efficiently), but this is
119 just a matter of discipline and common sense, not one of Org's design.
121 Read [[https://orgmode.org/list/0277B507-1486-4172-B1C6-1B73B84148DD@science.uva.nl][Carsten's enlightening statement]] on this.
122 ** What is the meaning of the Unicorn on Org's website?
129 The Unicorn is the logo of Org-mode because:
131 - Org-mode is the UNICs of ORgaNizers.
133 - Org-mode is an Emacs mode, so it makes sense to use an animal
134 similar or related to the gnu used for GNU Emacs.
136 - Org-mode is meant to show you the way, and an animal with two horns
137 can not do this very well, can it?
139 - Unicorn tears are said to reverse petrification, and wasn't this how
140 we all felt before getting to some degree of time and task
143 - It will take forever to learn everything there is to know about a
146 - A unicorn is a fabulous creature. Org-mode wants to be a fabulous
149 Using a unicorn was originally /Bastien Guerry's/ idea. His friend,
150 the french artist [[http://intemperies.over-blog.com/][Christophe Bataillon]], designed the logo for us, and
151 /Greg Newman/ gave it a refresh some time later. Bastien writes why
155 The first reason is not linked to the animal, but to the sounding of the
156 word "Unicorn" - because Org gives you a /uni/que way of producing files
157 in several format (HTML, LaTeX, etc.).
159 The second reason is that a Unicorn doesn't really exist, it is just
160 something you can dream about, and make others believe it does exist.
161 Just like the perfect organizer.
164 There was a [[https://orgmode.org/list/49A5BF02.1090400@rk-f.me][thread about unicorns]] on the mailing list. [[https://orgmode.org/list/49A5BF02.1090400@rk-f.me][Christopher
165 Suckling]] posted a link showing how to make a simple foldable unicorn
166 (very appropriate for an outlining program!).
168 [[https://orgmode.org/list/18859.6342.338919.506488@nitrogen.rketburt][Tim Burt]] made a very complicated one which is now a treasured
169 possession of the Org-mode author.
171 - Official logo: [[https://orgmode.org/img/org-mode-unicorn.png]]
172 This logo is available in a number of different formats including
173 Photoshop /.psd/ and scaleable vector graphics /.svg/ [[https://orgmode.org/img/][here]].
175 - An [[https://orgmode.org/img/nrocinu4.jpg][alternative version]] from Christophe Bataillon (c):
177 - [[https://orgmode.org/list/B7CC380355F946DF8DCA0392A362CDB6@CUBE][Chris Randle]] made a [[https://orgmode.org/img/nrocinu.txt][text version]] using the logo and [[http://glassgiant.com][glassgiant.com]]:
179 - [[https://orgmode.org/list/43B268EF-3DDC-439F-B0DB-85B09974B037@nf.mpg.de][Stefan Vollmar]] made a [[https://orgmode.org/img/nrocinu.pdf][pdf version]] (here in [[https://orgmode.org/img/nrocinu_pdf.png][png]]) using "a simple
180 threshold technique".
182 - [[https://orgmode.org/list/18859.6342.338919.506488@nitrogen.rketburt][Tim Burt]] made a folded Unicorn to match the spirit of Org - see the
183 whole set of pictures [[http://www.flickr.com/photos/tcburt/sets/72157614543357071/][on his flickr page]].
185 - Are unicorns real? Answer [[https://orgmode.org/list/87ljrru3vc.fsf@rosslaird.info][here]] by Ross Laird.
187 ** Is Org's documentation written in Org?
189 As of january 2018, yes. You can access the =.org= source of the manual
190 [[https://code.orgmode.org/bzg/org-mode/raw/master/doc/org-manual.org][on the repository]].
192 Previously, Org documentation was written in TeXinfo, which is the
193 standard format for Emacs documentation. You can export =.org= files to
194 texinfo using [[http://pandoc.org/][Pandoc]].
196 ** Is there a bibtex entry for the Org manual?
198 Yes. Please evaluate this function and run =M-x
199 org-insert-manual-bibtex-citation-at-point RET=.
201 #+begin_src emacs-lisp
202 (defun org-insert-manual-bibtex-citation-at-point ()
203 "Insert a BibTeX citation of the Org manual at point."
206 "@book{dominik10:_org_mode_refer_manual,
207 author = {Carsten Dominik},
208 title = {The Org-Mode 7 Reference Manual: Organize
209 Your Life with GNU Emacs},
210 publisher = {Network Theory},
213 note = {with contributions by David O'Toole, Bastien Guerry,
214 Philip Rooke, Dan Davison, Eric Schulte, and Thomas
217 (message "Thanks for quoting the Org manual!")))
220 Please check [[file:org-papers.org][the Org papers page]] for more references related to Org.
222 ** I think my Org-mode is broken! How do I report a bug?
224 :CUSTOM_ID: bug-reporting
229 1. Make sure you are running [[#updating-org][the latest version of Org-mode]].
231 2. Read [[https://orgmode.org/manual/Feedback.html][the Feedback section]] of the manual.
233 3. Provide a minimal example that duplicates the bug.
235 - Create a minimal .emacs file and start emacs with that file as
236 detailed in [[#minimal-emacs][these instructions]].
238 - Create a sample, minimal .org file that reliably reproduces the
239 problem and post it to the mailing list.
241 - Some users call this an "[[#ecm][ECM]]", a French acronym that means a
242 "minimal complete example".
251 This is a French acronym used by some mailing list members; it
252 stands for "Exemple Complet Minimal", or "Complete Minimal
253 Example". The term refers to test files that can reliably reproduce
254 a bug with the minimal amount of code. When you report a bug to the
255 mailing list, you should provide a minimal .org file (with no more
256 text than necessary) that demonstrates the bug. See [[https://orgmode.org/list/80oc3s13rg.fsf@somewhere.org][this post]] for
259 ** What should I do before contacting the mailing list?
261 :CUSTOM_ID: when-to-contact-mailing-list
264 The Org-mode mailing list is a high volume list, in which community
265 members discuss use cases, configuration, bugs, and developments.
267 If you are new to Org-mode, please read/search the excellent [[https://orgmode.org/manual/index.html][manual]]
268 (and pay special attention to the indexes) before asking your
271 You should also search the mailing list at [[http://lists.gnu.org/archive/html/emacs-orgmode/][lists.gnu.org]] or
272 [[https://orgmode.org/list/][orgmode.org/list]] to see if your issue has already been discussed.
274 See [[#can-org-do-x][this faq]] for more details.
276 ** Why hasn't my email to the mailing list shown up yet?
278 :CUSTOM_ID: ml-post-delay
281 The org-mode mailing list is moderated. Thus, if you are not
282 subscribed to the mailing list, your mail will only appear on the
283 list after it has been approved by a moderator. To ensure that your
284 mail appears quickly, please [[http://lists.gnu.org/mailman/listinfo/emacs-orgmode][subscribe to the list]].
286 ** I read the mailing list through gmane. Should I subscribe?
288 :CUSTOM_ID: ml-subscription-and-gmane
293 The org-mode mailing list is available via nntp at
294 =news.gmane.io/gmane.emacs.orgmode=. Many participants in the list
295 prefer to read the list in a newsreader, such as Gnus, instead of
296 receiving emails. If you choose to read the list via nntp, you can
297 still [[http://lists.gnu.org/mailman/listinfo/emacs-orgmode][subscribe]] to the list and then opt not to receive any emails
298 on the mailman settings page (see the "Mail Delivery" setting).
300 This will ensure that your messages to the list get through
301 quickly, reduce the work load of the mailing list moderators (who
302 need to clear every mail from non-members), and provide more
303 accurate information about the number of list readers.
307 :CUSTOM_ID: Keeping-current
309 ** Upgrading to Org 8.0/master and using the new export engine
311 :CUSTOM_ID: new-exporter-switch
314 #+index: Upgrade!new exporter
315 #+index: Export!new exporter
317 See [[file:org-8.0.org][Upgrading to Org 8.0 (or the current master branch)]].
319 ** My Emacs ships with an older version Org-mode! How do I upgrade?
321 :CUSTOM_ID: updating-org
326 Org-mode develops quickly, which means that versions of Org-mode
327 shipped with Emacs are more or less out-of-date. If you'd like to
328 upgrade to the most recent version of org-mode, you have a number of
331 1. Download the [[https://orgmode.org/index.html#sec-3][most recent release]] of org-mode as zip or tarball and
332 follow the [[https://orgmode.org/manual/Installation.html#Installation][installation instructions]] in the manual.
333 2. Clone and install the development git repository as [[#keeping-current-with-Org-mode-development][explained
334 here]]. If you don't want to run the bleeding edge, you can still
335 use git [[#using-stable-releases-only][to track the most recent stable releases]].
336 3. Install and updated org-mode automatically through the Emacs
337 Package Manager as [[#installing-via-elpa][explained in this FAQ]].
339 /Note/: Please also see [[#mixed-install][Is my Orgmode installation mixed?]] for a common
340 issue with mixed installations.
342 ** How do I keep current with bleeding edge development?
344 :CUSTOM_ID: keeping-current-with-Org-mode-development
347 #+index: Bleeding Edge
349 Org-mode is developed in [[https://en.wikipedia.org/wiki/Git_(software)][Git]]. You can keep up-to-date with Org-mode
350 developement by cloning the Org-mode repository and refreshing your
351 copy with latest changes whenever you wish. You only need to use
352 two Git commands (clone and pull.) Here are the steps in brief
353 (assuming a POSIX compatible shell and please customize locations
356 1. Select a location to house the Org-mode repository (approx. 40
357 MB; includes documentation, compiled elisp files and history
358 going all the way back to v4.12a)
360 : $ mkdir $HOME/elisp && cd $HOME/elisp
362 2. Clone the Org-mode Git repository.
364 Recommended approach:
366 : $ git clone git@code.orgmode.org:bzg/org-mode.git
368 (See [[file:worg-git.org::*The%20first%20time%20you%20contribute%20to%20Worg][The first time you contribute to Worg]] for how to gain access).
370 3. Compile and install Org-mode and build documentation.
372 : $ cd $HOME/elisp/org-mode && make
374 Please note that you can choose to /not/ compile at all and run
375 using source =.el= files only (compiled files speed things up),
376 but you will still need to generate the autoload files.
378 : $ cd $HOME/elisp/org-mode && make uncompiled
380 If you'd like to install org-mode someplace outside the source
381 tree (private or system-wide), you should edit =local.mk= to
382 point to the appropriate install location. You may need
383 administrator rights to do a system-wide installation.
385 : $ cd $HOME/elisp/org-mode && make install
387 4. This is where you configure Org-mode with Emacs. Please refer
388 to [[./org-tutorials/index.org][Org tutorials]].
390 5. Keeping up-to-date.
392 Cloning the repository is a one time activity. From this point
393 onwards you only need to /pull/ the latest changes, which the
394 Makefile is set up to do automatically for certain make targets.
396 : $ cd $HOME/elisp/org-mode && make update
398 or if you immediately want to install as well
400 : $ cd $HOME/elisp/org-mode && make update2
402 Actually in this case it is recommended to run the test suite
403 before installation so that you don't install a version that
406 : $ cd $HOME/elisp/org-mode && make up2
408 6. You should reload Org-mode to have the changes take effect (if
409 you are not restarting Emacs, which is recommended). Also since
410 the intention is to "keep up" with Org-mode, you should visit
411 updated sections of documentation for latest updates (use =git
414 7. As you use your repository over time it will accumulate loose objects.
415 You can reduce the total size of your git repository with
419 which will consolidate loose git objects into pack files. This
420 reduces the size of the repository and speeds up data access to
423 ** How do I update the info manual pages to the latest org-mode version?
425 :CUSTOM_ID: update-info-manual-to-latest
428 *This is not a problem if org-mode is installed system-wide, which
429 automatically takes care of this issue!* Since org-mode already
430 ships with Emacs, a rather common problem among users is "How do I
431 update the info documentation to the latest version of org-mode?".
432 There are three ways to achieve this if for whatever reason you
433 can't install into the standard, system-wide info directory:
435 1. You can set the =INFOPATH= environment variable in your login
438 #+begin_src shell-script :eval no
440 export INFOPATH=/path/to/org-mode/info:$INFOPATH
444 =/path/to/org-mode/info= is wherever you install org-mode.
446 2. You can achieve the same with elisp like this:
448 #+begin_src emacs-lisp :eval no
450 (add-to-list 'Info-additional-directory-list
451 (expand-file-name "/path/to/org-mode/info"))
454 3. You should specify the same location in the Makefile while
455 installing org-mode like this:
457 #+begin_src makefile-gmake :eval no
458 # Where local software is found
459 prefix=/path/to/emacs-root
461 # Where info files go.
462 infodir = $(prefix)/share/info
465 ** How can I keep local changes and still track Org-mode development?
467 :CUSTOM_ID: keeping-local-changes-current-with-Org-mode-development
470 There is no need to do this anymore for the purpose of adapting the
471 build system to the local environment, since this can now be
472 specified in =local.mk=. However, there may be a need to make other
473 local changes to Org.
475 Say you want to make minor changes to the =org.el= or any other
476 version controlled file from Org and you want to keep these changes
477 on top of the =master= branch from Org. Create a local branch for
478 your changes on top of origin/master as follows:
480 : $ git checkout -b local origin/master
481 : $ git config branch.local.rebase true
482 : # Make your changes to the sources and create a new commit
483 : $ git commit -am 'My local changes to Org'
484 : # Update to a newer version
487 Now each time you pull new commits from the distribution repository
488 your local commits will be rewound and replayed on top of the new
489 origin/master. You would normally work on your =local= branch which
490 includes your custom commits; there's no need to switch back to the
493 If you get a conflict during a =git pull= (a change in Org and one
494 of your local changes try to alter the same line of code) you will
495 need to edit the file with the conflict to fix up the conflicting
496 lines and then tell git that you have resolved the conflict:
498 1. =git pull= fails with a conflict
499 2. edit the file: look for the conflict markers =>>>>>>>= and
500 =<<<<<<<= and either keep one version or create a new one and
501 remove all conflict markers while doing this.
502 3. =git add= the file to the index to mark the conflict resolved
503 4. =git rebase --continue=
504 5. lather, rinse, and repeat 2-4 as needed
506 Note that it is possible to have silent conflicts when a change in
507 Org and one of your local changes do not edit the same line of code,
508 but are logically incompatible — for example Org might have changed
509 to assume /roses are red/ while you've made a local change that
510 defines /my roses are yellow/ in some other place. Git will not
511 warn you about such conflicts (it doesn't understand what the code
514 At anytime during the rebase conflict resolution you can say "oops
515 this is all wrong - put it back the way it was before I did a pull"
517 : $ git rebase --abort
519 ** How can I use a stable release version instead of the bleeding edge master?
521 :CUSTOM_ID: using-stable-releases-only
524 The =master= branch of the git repository always contains the bleeding
525 edge development code. This is important for Org's fast development,
526 because code on master gets checked out by many people daily and we
527 quickly receive bug reports if something is wrong. On rare occasions,
528 this code may not function perfectly for a limited time while we are
529 trying to fix things. It is therefore recommended to keep a
530 known-good version of org-mode installed outside the source tree and
531 always run the full test suite before using a new version from master.
533 Not everyone like to use this bleeding-edge code and face the danger
534 to hit a surprising bug. The branch =maint= is specifically for
535 collecting only fixes for known bugs between releases. If you don't
536 want to wait for a new release, but don't want to live on the bleeding
537 edge, consider using =maint=.
539 From time to time, we make a release by merging all the new features
540 from =master= into =maint=. This typically happens when the
541 maintainers feel that
543 1. they have reached a good point in the development
544 2. the code has a feature set that should stay and be supported in the
547 Stable releases are used as the basis for [[https://orgmode.org/index.html#sec-3_3][alternative distributions]] of
548 Org, and they are also the code that gets merged into the Emacs
549 distribution. If you want to work only with stable releases, you can
550 always download [[https://orgmode.org/index.html#sec-3][them here]], but you can also also use the git
551 repository to keep automatically up-to-date with the most recent
552 stable releases (and save bandwidth!). Here's how to do so:
554 *** Run a specific stable release
556 In the repository, do
561 To see which release tags are available. Let's say you decide to use
564 : $ git checkout release_7.01f
566 This set the working tree of the repository to the state of Org at the
567 moment of release 7.01f. You can then run Org from the repository be
568 sure to use the stable release while development continues on the
571 Later, when we release 7.02, you can switch to that using
573 : $ git fetch --tags # to get all the new stuff
575 : $ git checkout release_7.02
577 *** Always run the most recent stable release
579 Alternatively, if you just want to always run whatever the latest
580 stable release is, you can do
582 : $ git checkout -b stable origin/maint
584 and then regularly update this branch by doing
588 ** How can I install an up-to-date version of org-mode without "make" tools?
590 :CUSTOM_ID: installing-org-without-make-tools
593 If you are using org-mode on a computer that lacks developer tools for
594 compiling software, such as [[http://www.gnu.org/software/make/][GNU Make]], you will have to use a
595 *different* installation method than [[https://orgmode.org/manual/Installation.html#Installation][the one outlined in the manual]].
596 Please see this description for [[https://orgmode.org/worg/org-hacks.html#compiling-org-without-make][compiling org-mode without make]] so you
597 can install a recent version of org-mode without using the full build
600 ** I don't use git. Can I download bleeding edge .zip and .tar.gz archives?
602 Yes. You can download [[https://orgmode.org/org-latest.zip][org-latest.zip]] or [[https://orgmode.org/org-latest.tar.gz][org-latest.tar.gz]] of Org-mode --
603 these archives are updated every day at midnight.
605 Alternatively, you can download a [[https://code.orgmode.org/bzg/org-mode/releases][tar.gz release archive]].
607 ** How do I install Org-mode through Emacs' Package Manager?
609 :CUSTOM_ID: installing-via-elpa
612 Daily builds of Org-mode are distributed as an ELPA package from both
613 [[http://elpa.gnu.org/packages/][GNU Emacs Lisp Package Archive]] as well as from the [[https://orgmode.org/elpa/][Org-mode Emacs Lisp
616 Steps for installing Org with package manager:
617 1) Do =M-x list-packages= to browse available packages.
618 2) If the above command is unavailable you need to [[#installing-elpa][install the package
619 manager]] before proceeding ahead.
620 3) If you see =org= as an available package, skip to step 5.
621 4) If you are here it means that org is unavailable in the GNU's
622 archives. Report this discrepancy to [[mailto:emacs-orgmode@gnu.org][Orgmode mailing list.]]
624 In the meanwhile, you can manually download the tarball and
625 install it. Refer [[*How do I install Org-mode from a ELPA-compatible tarball?][to this FAQ entry]] for further information.
626 5) Press =i= to mark the package for installation
627 6) Press =x= to install
629 8) Use =M-x locate-library RET org=. If your installation is
630 successful you would something like the following:
632 =Library is file ~/.emacs.d/elpa/org-20110403/org.elc=
634 # 7) If you get the following error "*Failed to download `Org-mode'
635 # archive.*" in step 2, you can manually download the tarball and
638 # 8) Add Orgmode as a package archive. This can be done in two ways:
639 # 9) Use =M-x customize-variable RET package-archives=
640 # 10) Add the following line to your =.emacs= and reload Emacs.
641 # #+begin_src emacs-lisp
642 # (add-to-list 'package-archives '("Org-mode" . "https://orgmode.org/elpa/"))
646 ** How do I install Emacs package manager?
648 :CUSTOM_ID: installing-elpa
651 If you are running Emacs 24 or find the command =M-x list-packages=
652 available you already have the package manager installed.
654 Steps for installing package manager on emacs-23:
656 1. Download the package manager [[http://repo.or.cz/w/emacs.git/blob_plain/1a0a666f941c99882093d7bd08ced15033bc3f0c:/lisp/emacs-lisp/package.el][package.el]]
658 2. Add the following to your =.emacs= and reload Emacs.
659 #+begin_src emacs-lisp
660 ;; change "~/elisp/" as appropiate
661 (setq load-path (cons "~/elisp" load-path))
663 ;; Add the below lines *at the beginning* of your .emacs.
668 ** I don't see Org-mode as an installation option in Package Manager Menu?
670 :CUSTOM_ID: why-no-org-in-elpa
673 Emacs Package Manager is a very recent addition to Emacs. Work is
674 under way to have have Org-mode seamlessly integrate with Emacs'
675 Package Manager. As a result, it will be some time before the
676 Org-mode packages are available and usable from either GNU or
677 Org-mode package archives.
679 In the meanwhile, you can install Org-mode via package manager
680 through ELPA-compatible tar. Refer [[#installing-from-elpa-tarball][to this FAQ entry]] for more
683 ** How do I install Org-mode from a ELPA-compatible tarball?
685 :CUSTOM_ID: installing-from-elpa-tarball
690 Org-mode is distributed as an ELPA-compatible tar which can be used
691 in conjunction with Emacs' package manager.
693 1. If you are already running Org-mode, note the current version
694 reported by M-x org-version.
695 2. Download the latest tarball from [[https://orgmode.org/elpa/][Org-mode repo]].
696 3. Do =M-x package-install-file=. When prompted for =Package file
697 name=, point it to .tar file downloaded in step 2.
699 You will now see Package Manager compiling the files and
701 4. Reload emacs. This step is very important.
702 5. Note the version of the new installation using M-x
703 org-version. If the new and old versions are different, the
704 installation is done and you are all set to enjoy the updated
705 Org-mode. Otherwise skip to step 6.
706 6. Review you load-path using =C-h v load-path=. Most likely that
707 your old installation path takes precedence over the path chosen
708 by package manager (which is typically
709 =~/.emacs.d/elpa/...=). Fix this anamoly by moving
710 =(package-initialize)= line in .emacs to a more appropriate
713 ** Why would I use ELPA tarballs instead of the snapshot tarballs?
720 ELPA-tarballs automate much the process of upgrading org-mode. Much
721 of the following grunt work is done automatically by the Package
724 1. Downloading, compiling, and activating of org-mode (including
725 setting org-mode's =load-path= and autoloads).
726 2. Updating info files.
735 ** How can I quickly browse all Org options?
739 =M-x org-customize RET=
741 See also [[file:org-tutorials/org-customize.org][Carsten's Org customize tutorial]] and [[file:org-configs/org-customization-guide.org][this customization guide]]
744 ** Can I use the editing features of org-mode in other modes?
746 :CUSTOM_ID: use-editing-features-in-other-modes
749 Not really---but there are a few editing features you can use in
752 - For tables there is =orgtbl-mode= which implements the table
753 editor as a minor mode. (To enable, type =M-x orgtbl-mode=)
754 - For ordered lists there is =orgstruct-mode= which allows for easy
755 list editing as a minor mode. (To enable, type =M-x
758 You can activate these modes automatically by using hooks:
760 : (add-hook 'mail-mode-hook 'turn-on-orgtbl)
761 : (add-hook 'mail-mode-hook 'turn-on-orgstruct)
763 For footnotes, there is the function =org-footnote-action=, which
764 works in non-org buffers. This function is a powerful tool for
765 creating and sorting footnotes. To use it globally, you can add the
766 following keybinding to your =.emacs= file (requires Org 6.17 or
769 : (global-set-key (kbd "C-c f") 'org-footnote-action)
771 For other features you need to switch to Org-mode temporarily, or
772 prepare text in a different buffer.
774 ** Why isn't feature "X" working the way it is described in the manual?
776 :CUSTOM_ID: making-sure-org-mode-is-up-to-date
779 Org-mode develops very quickly. If you are using a version of Org-mode
780 that shipped with emacs, there is a good chance that it is somewhat
783 Many of the users on the Org-mode mailing list are using either a
784 recent release of Org-mode or the
785 [[https://orgmode.org/index.html#sec-3.2][development version of
786 org-mode from the git repository]].
788 If some settings and features aren't working the way you expect, make
789 sure that the version of the manual you are consulting matches the
790 version of Org-mode you are using.
792 - You can check which version of Org-mode you are using by
793 selection =Org --> Documentation --> Show Version= in the Emacs
796 - The [[https://orgmode.org/manual/index.html][online manual]] at [[https://orgmode.org][orgmode.org]] corresponds to the most recent
799 - The [[http://www.gnu.org/software/emacs/manual/html_node/org/index.html][manual]] at [[http://www.gnu.org][www.gnu.org]] corresponds to the version of Org-mode
800 released with the latest official Gnu Emacs release. Compared
801 with the manual at the orgmode.org, the manual at www.gnu.org is
802 somewhat out of date.
804 For instructions on how to stay current with Org-mode, consult [[#keeping-current-with-Org-mode-development][this
805 FAQ]] or follow the instructions on [[https://orgmode.org][the official Org-mode site]].
807 ** Can I get the visibility-cycling features in emacs-lisp-mode?
809 Yes. This snippet in your =.emacs= will bind =C-M-]= and =M-]= to global
812 #+BEGIN_SRC emacs-lisp
813 (global-set-key (kbd "C-M-]") (lambda () (interactive) (org-cycle t)))
814 (global-set-key (kbd "M-]") (lambda ()
818 (beginning-of-defun))
822 ** Can I get the visibility-cycling features in outline-mode and outline-minor-mode?
824 :CUSTOM_ID: use-visibility-cycling-in-outline-mode
827 #+index: Visibility!Cycling
829 Yes, these functions are written in a way that they are independent of
830 the outline setup. The following setup provides standard Org-mode
831 functionality in outline-mode on =TAB= and =S-TAB=. For
832 outline-minor-mode, we use =C-TAB= instead of =TAB=,
833 because =TAB= usually has mode-specific tasks.
835 #+BEGIN_SRC emacs-lisp
836 (add-hook 'outline-minor-mode-hook
838 (define-key outline-minor-mode-map [(control tab)] 'org-cycle)
839 (define-key outline-minor-mode-map [(shift tab)] 'org-global-cycle)))
840 (add-hook 'outline-mode-hook
842 (define-key outline-mode-map [(tab)] 'org-cycle)
843 (define-key outline-mode-map [(shift tab)] 'org-global-cycle)))
846 Or check out /outline-magic.el/, which does this and also provides
847 promotion and demotion functionality. /outline-magic.el/ is
848 available at [[http://www.astro.uva.nl/~dominik/Tools/outline-magic.el][Outline Magic]].
850 ** Can I save and restore the visibility state of an org-mode buffer?
852 :CUSTOM_ID: saving-visibility-state
855 #+index: Visibility!Restore
857 Well, no---at least not automatically. You can, however, control the
858 visibility of an org-file or of individual trees by adding
859 instructions to your org file. See [[https://orgmode.org/manual/Visibility-cycling.html#Visibility-cycling][this section of the manual]] for more
862 ** How can I keep track of changes in my Org files?
864 :CUSTOM_ID: track-of-changes-in-Org-files
867 Use git to track the history of the files, use a cronjob to check in
868 changes regularly. Such a setup is described by Bernt Hansen in
869 [[https://orgmode.org/list/87tzilzgkv.fsf@gollum.intra.norang.ca][this message]].
871 ** Can I use Org-mode as the default mode for all README files?
873 :CUSTOM_ID: Org-mode-as-default-mode
876 #+index: default-major-mode
878 Add the following to your .emacs file:
880 : (add-to-list 'auto-mode-alist '("README$" . org-mode))
882 You can even make it the default mode for any files with unspecified
885 : (setq default-major-mode 'org-mode)
887 ** Can I use ido.el for completing stuff in Org?
889 :CUSTOM_ID: ido-complete
894 Yes, you can. If you are an ido user and ido-mode is active, the
895 following setting will make Org use =ido-completing-read= for most
896 of its completing prompts.
898 : (setq org-completion-use-ido t)
900 ** Should I use one big org file or multiple files?
902 :CUSTOM_ID: how-to-organize-org-mode-files
905 Org-mode is flexible enough to accomodate a variety of organizational and
906 time management schemes. Org's [[https://orgmode.org/manual/Document-structure.html#Document-structure][outline cycling and convenient editing and
907 navigation commands]] make it possible to maintain all of your projects and
908 notes in a single file. But org-mode's [[https://orgmode.org/manual/Hyperlinks.html#Hyperlinks][quick and easy hyperlinks]], along
909 with [[https://orgmode.org/manual/Refile-and-copy.html#Refile-and-copy][easy refiling of notes and todos]], also make it a delight to maintain a
910 private "wiki" consisting of multiple files.
912 No matter how you organize your org files, org-mode's agenda commands
913 make it easy to search all your notes and gather together crucial data
916 Moreover, several org-mode settings can be configured either globally in
917 your =.emacs= file or locally (per file or per outline tree). See the
918 [[https://orgmode.org/manual/index.html#Top][manual]] for more details. For an example of local customizations see [[#limit-agenda-with-category-match][this
921 Here are a few ideas for organizing org-mode files:
923 - A single file for all your projects and notes.
924 - One file per project.
925 - One file per client.
926 - One file per area of responsibility or type of work (e.g.,
927 household, health, work, etc.).
928 - One file for projects, one for appointments, one for reference
929 material, one for someday/maybe items, etc.
930 - A wiki of hyperlinked files that grows and adapts to meet your
933 For more ideas, see some of the links on the [[file:org-tutorials/index.org][org-tutorial index]] or
934 [[file:org-gtd-etc.org][this page on org-mode and GTD]].
936 ** Why doesn't C-c a call the agenda? Why don't some org keybindings work?
938 :CUSTOM_ID: setting-global-keybindings
941 Org-mode has a few global keybindings that the user must set explicitly in
942 an =.emacs= file. These keybindings include the customary shortcut for
943 calling the agenda (=C-c a=). If nothing happens when you type =C-c a=,
944 then make sure that the following lines are in your =.emacs= file:
946 #+BEGIN_SRC emacs-lisp
947 ;; The following lines are always needed. Choose your own keys.
948 (add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode))
949 (global-set-key "\C-cl" 'org-store-link)
950 (global-set-key "\C-ca" 'org-agenda)
951 (global-set-key "\C-cb" 'org-iswitchb)
954 You may, of course, choose whatever keybindings work best for you
955 and do not conflict with other modes.
957 Please see [[https://orgmode.org/manual/Activation.html][this section of the manual]] if you have additional
960 ** Why aren't some of the variables I've customized having an effect?
962 :CUSTOM_ID: load-org-after-setting-variables
965 Some org variables have to be set before org.el is loaded or else they
966 will not work. (An example is the new variable
967 =org-enforce-todo-dependencies=.)
969 You should also make sure that you do not require any other =org-...=
970 files in your =.emacs= file before you have set your org variables,
971 since these will also cause org.el to be loaded. To be safe, load org
972 files *after* you have set your variables.
974 ** How can I make sure that timestamps appear in English?
976 :CUSTOM_ID: timestamps-and-system-time-locale
979 If your system's locale is not set to English, but you would like the
980 timestamps in your org-mode files to appear in English, you can set
981 the following variable:
983 #+begin_src emacs-lisp
984 (setq system-time-locale "C")
987 ** What does a minimal .emacs look like?
989 :CUSTOM_ID: minimal-emacs
992 Using a stripped down minimal .emacs files removes broken custom
993 settings as the cause of an issue and makes it easy to reproduce for
994 other people. The example below has system-specific paths that you'll
995 need to change for your own use.
997 #+begin_src emacs-lisp
998 (add-to-list 'load-path (expand-file-name "~/git/org-mode/lisp"))
999 (add-to-list 'auto-mode-alist '("\\.\\(org\\ |org_archive\\|txt\\)$" . org-mode))
1000 (setq org-agenda-files '("/tmp/test.org"))
1002 (require 'org-habit)
1004 (global-set-key "\C-cl" 'org-store-link)
1005 (global-set-key "\C-ca" 'org-agenda)
1006 (global-set-key "\C-cb" 'org-iswitchb)
1009 You can save the minimal .emacs file to ~/minimal.emacs, add suspect
1010 configuration code to it, then start emacs something like this:
1013 emacs -Q -l ~/minimal.emacs
1016 On OS X, starting emacs with minimal configuration might look
1017 something like this:
1020 /Applications/emacs.app/Contents/MacOS/Emacs -Q -l ~/minimal.emacs
1023 ** Can I migrate from Planner?
1025 Yes. This [[http://www.c0t0d0s0.de/plan2org/plan2org.pl][perl script]] or [[http://gitorious.org/bkuhn-small-hacks/org-mode/blobs/master/planner2org.plx
1026 ][this Perl script]] can help.
1028 * Errors and general problems
1032 ** Is my Orgmode installation mixed?
1034 :CUSTOM_ID: mixed-install
1036 Emacs is distributed with a version of Orgmode bundled with it. A
1037 common problem among users who install a [[#updating-org][newer version]] of Orgmode
1038 separately is a mixed install where Emacs loads some files from the
1039 bundled and the rest from the latest version. This can lead to
1040 /unending/ troubles in the future. With a recent installation of
1041 Org mode =M-x org-version= will indicate if the installation is mixed.
1043 With somewhat older Org mode installations, the procedure is more
1044 involved and indeterminate. An easy first step is to look
1045 at the output of =M-x org-version=.
1046 - Good :: ~Org-mode version 7.8.11 (release_7.8.11-448-g1737d3 @
1047 /path/to/org-mode/lisp/)~
1048 - Bad :: ~Org-mode version 6.33x (release_7.8.11.409.ga3778)~
1050 A second step is to go through the output of =list-load-path-shadows=
1051 line-by-line to get hints to what in your configuration is causing
1052 the issue. Among the most common reasons is Orgmode gets loaded
1053 before the =load-path= variable is updated to include the
1054 installation directory of the latest Orgmode. To avoid issues like
1055 this, it is recommended that the load path is updated very early on
1058 /Note:/ The formatting of the version information, as shown in the
1059 examples above, will be different for older Org mode releases,
1060 e.g. ~Org-mode version 7.8.02~.
1062 ** Opening Org files in Emacs leads to a crash
1064 :CUSTOM_ID: Emacs-crashes-with-org-indent-mode
1066 The only known case where Org-mode can crash Emacs is when you are
1067 using =org-indent-mode= with Emacs 23.1 (in fact, any version of
1068 Emacs before version 23.1.50.3). Upgrade to Emacs 23.2 and the
1069 problem should go away.
1071 ** When I try to use Org-mode, I always get the error message =(wrong-type-argument keymapp nil)=
1073 :CUSTOM_ID: wrong-type-argument-keymapp
1076 This is a conflict with an outdated version of the /allout.el/, see
1077 the [[https://orgmode.org/manual/Conflicts.html#Conflicts][Conflicts]] section in the manual
1079 ** How can I control the application launched by Org-mode to open a certain file type like pdf, html...?
1081 :CUSTOM_ID: external-application-launched-to-open-file-link
1084 If you want special control about how Org-mode opens files, see the
1085 variables =org-file-apps=, =org-file-apps-defaults-gnu=,
1086 =org-file-apps-defaults-macosx=, =org-file-apps-defaults-windowsnt=.
1088 *However*, normally it is best to just use the mechanism the
1089 operating-system provides:
1091 *** GNU/Linux systems
1092 You you have to check your mailcap settings, find the files:
1100 and modify them accordingly. Please read their manual entry.
1103 + for html pages you may configure the =browse-url-= variables through
1104 the Customize interface,
1105 + the pdf files are automatically opened with Acrobat Reader (if it is
1109 Change the application responsible for this file type by selecting
1110 such a file in the Finder, select =File->Get Info= from the menu
1111 and select the application to open this file with. Then, to
1112 propagate the change to all files with the same extension, select
1113 the =Change all= button.
1115 ** Org-mode takes over the TAB key. I also want to use YASnippet, is there a way to fix this conflict?
1117 :CUSTOM_ID: YASnippet
1120 [[http://code.google.com/p/yasnippet/][yasnippet]] is yet another snippet expansion system for Emacs. It is
1121 inspired by TextMate's templating syntax.
1122 - watch the [[http://www.youtube.com/watch?v=vOj7btx3ATg][video on YouTube]]
1123 - see the [[http://yasnippet.googlecode.com/svn/trunk/doc/index.html][intro and tutorial]]
1125 *Note*: yasnippet is not compatible with =org-indent-mode= currently
1126 there is no known way to use both successfully with =yas/trigger-key=
1127 set to =TAB= (or =[tab]= etc...)
1129 The way Org-mode binds the =TAB= key (binding to =[tab]= instead of
1130 =\t=) overrules yasnippets' access to this key. The following code
1133 #+begin_src emacs-lisp
1134 (add-hook 'org-mode-hook
1136 (org-set-local 'yas/trigger-key [tab])
1137 (define-key yas/keymap [tab] 'yas/next-field-group)))
1140 If the above code doesn't work (which it may not with later versions
1141 of yasnippet). Then try the following
1143 #+begin_src emacs-lisp
1144 (defun yas/org-very-safe-expand ()
1145 (let ((yas/fallback-behavior 'return-nil)) (yas/expand)))
1147 (add-hook 'org-mode-hook
1149 ;; yasnippet (using the new org-cycle hooks)
1150 (make-variable-buffer-local 'yas/trigger-key)
1151 (setq yas/trigger-key [tab])
1152 (add-to-list 'org-tab-first-hook 'yas/org-very-safe-expand)
1153 (define-key yas/keymap [tab] 'yas/next-field)))
1156 Rick Moynihan maintains a [[http://github.com/RickMoynihan/yasnippet-org-mode][git repository]] (or [[http://github.com/eschulte/yasnippet-org-mode][Eric's fork of the same]])
1157 with YASnippets for Org-mode.
1159 ** Org-mode takes over the S-cursor keys. I also want to use CUA-mode, is there a way to fix this conflict?
1161 :CUSTOM_ID: CUA-mode
1164 Yes, see the [[https://orgmode.org/manual/Conflicts.html#Conflicts][Conflicts]] section of the manual.
1166 ** Org-mode takes over the S-cursor keys. I also want to use windmove.el, is there a way to fix this conflict?
1168 :CUSTOM_ID: windmove.el
1171 Yes, see the [[https://orgmode.org/manual/Conflicts.html#Conflicts][Conflicts]] section of the manual.
1173 ** Org behaves strangely: some keys don't work, some features are missing, my settings have no effect, ...
1175 :CUSTOM_ID: loaded-old-org
1178 When this sort of things happen, it probably is because Emacs is
1179 loading an old version of Org-mode instead of the one you expected.
1180 Check it with =M-x org-version=.
1182 This happens because Emacs loads first the system org-mode (the one
1183 included with Emacs) before the one in your directory. Check the
1184 =load-path= variable; you might see that your org-mode appears /after/
1185 the system-wide path; this is bad.
1187 You should add your directories to the =load-path= at the beginning:
1189 : (add-to-list 'load-path "~/.emacs.d/org-mode/lisp")
1191 Function =add-to-list= adds at the beginning. Don't use =append= because
1192 it appends at the end.
1194 This wrong version loading may also happen if you have a byte-compiled
1195 =org.elc= from an old version together with a new =org.el=. Since
1196 Emacs prefers loading byte-compiled files (even if the =.el= is
1197 newer), it will load the old Org-mode.
1199 ** Why doesn't org-batch-agenda work under Win32?
1201 :CUSTOM_ID: org-batch-agenda-under-win32
1204 When I run the example batch files to print my agenda to the console
1205 under Win32 I get the failure:
1207 : End of file during parsing
1209 and no agenda is printed.
1211 The problem is the use of single quotes surrounding the eval in the
1212 emacs command-line. This gets confused under Win32. All string
1213 parameters with spaces must be surrounded in double quotes. This means
1214 that double quotes being passed to the eval must be escaped.
1216 Therefore, instead of the following:
1218 : <path to emacs>\emacs.exe -batch -l ~/_emacs_org \
1219 : -eval '(org-batch-agenda "a")'
1221 you need to use the following:
1223 : <path to emacs>\emacs.exe -batch -l ~/_emacs_org \
1224 : -eval "(org-batch-agenda \"a\")"
1226 (all on one line, of course).
1228 ** Org agenda seems very slow
1230 :CUSTOM_ID: slow-agenda
1233 If it takes a long time to generate or refresh the agenda, you might
1234 want first check which version of org-mode you are using. There have
1235 been major optimizations of org-agenda since 6.21b, which was the
1236 version of org-mode released with Emacs 23. If you are using 6.21b or
1237 earlier (you can check with =M-x org-version=), then you might want to
1238 consider upgrading to a more recent version of org-mode.
1240 Here are some other ideas for speeding up the agenda:
1242 1. Use a one day agenda view (rather than a seven day view).
1244 =(setq org-agenda-ndays 1)=
1246 2. Archive inactive items to separate files.
1248 =C-c C-x C-s= (org-archive-subtree)
1250 3. Do not include the global todo list in your agenda view.
1252 (setq org-agenda-include-all-todo nil)
1254 4. Make sure that your org files are byte-compiled.
1256 I.e., make sure there are files ending in =.elc= in your org
1257 installation directory.
1259 5. Limit your agenda files (=org-agenda-files=) to files that have
1260 active todos and or projects.
1262 If you have a number of older reference files---i.e., files you
1263 search only occasionally---in your agenda files list, consider
1264 removing them from your agenda files and adding them to
1265 =org-agenda-text-search-extra-files= instead. Similarly, you might
1266 consider searching some of your older reference files with =M-x
1267 grep= so that Org-mode does not have to load them into memory when
1268 the agenda is called.
1270 ** Visual-line-mode doesn't work well with Org-mode
1272 :CUSTOM_ID: visual-line-mode
1275 Visual-line-mode "soft wraps" lines so that the visual edge of the
1276 buffer is considered a line break for purposes of navigation, even
1277 though there is no line break in reality.
1279 In older versions of org-mode, org-beginning-of-line and
1280 org-end-of-line do not work well with visual line mode. (The two
1281 commands disregard soft line breaks and move to the beginning and end
1282 of the hard line break.) A patch was introduces to fix this behavior
1285 If you are using an older version of Org-mode, you can:
1287 1. Add a hook to turn off visual line mode.
1289 2. Add the following to your =.emacs=:
1291 #+begin_src emacs-lisp
1293 (add-hook 'org-mode-hook
1295 (define-key org-mode-map "\C-a" 'move-beginning-of-line)
1296 (define-key org-mode-map "\C-e" 'move-end-of-line)))
1299 ** Can I hide blocks at startup?
1303 #+begin_src emacs-lisp
1304 (setq org-hide-block-startup t)
1310 ,#+STARTUP: hideblocks
1313 on a per-file basis.
1315 ** After updating Org I get an error about an =invalid function=
1317 :CUSTOM_ID: invalid-function-error
1320 In almost all cases an =invalid function= error is caused by an
1321 unclean Org-mode source directory. Cleaning it up and recompiling
1322 should fix the problem
1324 : cd /path/to/orgmode
1328 In some cases, bits and pieces of org are loaded from various places (previous
1329 installs, the built-in install of org that came with whatever emacs version you have)
1330 and things get very confused. In all cases, cleaning up every last bit of org installation
1331 from everywhere and reinstalling org from git should restore sanity. See also the [[id:facac2a6-3526-450d-ac42-8d36b16c6bab][next question]].
1333 ** I use starter-kit and I get an error =(void-function org-pop-to-buffer-same-window)=
1335 :ID: facac2a6-3526-450d-ac42-8d36b16c6bab
1337 This is a particular instance of the [[#invalid-function-error][previous question]] but with some twists and turns,
1338 and a solution culled from various postings on the mailing list.
1340 starter-kit loads the site-file version of org (the one that came with
1341 your emacs install). Then when you load your init file, the local
1342 version is added to the front of load-path, so it looks as if things
1343 are originating there, but the damage is already done: you have a
1346 One possible solution is to add (package-initialize) to the primary init.el
1347 before starter-kit gets going. This will pick up the local install so
1348 that the built-in version never enters to muddy the picture.
1350 ** (Filling a paragraph|Indenting a list|...) behaves strangely
1351 Many filling/indenting problems have been reported on the mailing
1352 list: many of those were bugs (that have been fixed), but quite a lot
1353 are caused by people using the filladapt package, which is fundamentally
1354 incompatible with Org, which has its own facilities for these tasks. If you see
1355 strange behavior in this area, first check if you are using filladapt: visit an org
1356 file and check the modeline for "Filladapt".
1358 If filladapt is on, you want to turn it off before investigating
1359 further. Anthony Lander suggested on the mailing list the following
1360 method to turn off filladapt mode when you visit org files:
1362 #+BEGIN_SRC emacs-lisp
1363 (add-hook 'org-mode-hook 'turn-off-filladapt-mode)
1366 This should be placed in your .emacs (or other initialization file) after org
1369 * Faces and highlighting
1373 ** Org-mode has a lot of colors? How can I change them?
1375 :CUSTOM_ID: customizing-org-faces
1380 This is a question that applies to Emacs as a whole, but it comes up
1381 quite frequently on the org-mode mailing list, so it is appropriate to
1384 If you would like to change the style of a face in org-mode (or any
1385 other Emacs mode), simply type =M-x customize-face [RET]= while the
1386 cursor is on the color/style you are interested in modifying. You will
1387 be given the opportunity to customize all the faces located at that
1390 If you would like an overview of all the faces in org-mode, you can
1391 type =C-u M-x list-faces-display [RET] org= and you will be shown all
1392 the faces defined by org-mode along with an illustration of their
1395 If you would like to customize org-faces and other aspects of
1396 org-appearance, type =M-x customize-group org-font-lock [RET]=.
1398 Finally, if you would like verbose information about the properties of
1399 the text under the cursor, you can type =C-u C-x ==.
1401 See the Worg page on [[file:org-tutorials/org-appearance.org][customizing Org appearance]] for further information.
1402 ** Why do I get a tiny font in column view when using emacs daemon?
1404 :CUSTOM_ID: column-view-tiny-font
1407 #+index: Column view
1409 When using emacs in daemon mode (=emacs --daemon=), client frames
1410 sometimes override the column view face settings, resulting in very
1411 small fonts. Here is a fix:
1413 #+begin_src emacs-lisp
1414 (defun org-column-view-uses-fixed-width-face ()
1415 ;; copy from org-faces.el
1416 (when (fboundp 'set-face-attribute)
1417 ;; Make sure that a fixed-width face is used when we have a column
1419 (set-face-attribute 'org-column nil
1420 :height (face-attribute 'default :height)
1421 :family (face-attribute 'default :family))))
1423 (when (and (fboundp 'daemonp) (daemonp))
1424 (add-hook 'org-mode-hook 'org-column-view-uses-fixed-width-face))
1427 This fix was provided in the following mailing list post:
1429 https://orgmode.org/list/loom.20100715T095418-84@post.gmane.org
1430 ** How can I stop the mouse cursor from highlighting lines in the agenda?
1432 :CUSTOM_ID: ratpoison-for-agenda-highlighting
1435 #+index: Highlighting
1437 You can add the following to your =.emacs=:
1439 #+begin_src emacs-lisp
1440 (add-hook 'org-finalize-agenda-hook
1441 (lambda () (remove-text-properties
1442 (point-min) (point-max) '(mouse-face t))))
1449 ** Can I close an outline section without starting a new section?
1451 :CUSTOM_ID: closing-outline-sections
1456 Can I have nested, closed outline sections, similar to xml? This
1457 question comes up quite frequently on the mailing list.
1459 See the following threads:
1461 - https://orgmode.org/list/20110327170251.58923564@hsdev.com
1462 - https://orgmode.org/list/AANLkTinaTdYWQTXLzCf2kJVOMv64OM_5tL_0JCYAssPr@mail.gmail.com
1463 - https://orgmode.org/list/q2sc8f5e1e41004151315v433bc7b7udb98e65771a15340@mail.gmail.com
1464 - https://orgmode.org/list/49CE32EC.5060508@gmx.de
1466 The desired behavior looks something like this:
1481 ,# end Subsection Two
1483 Continue text in section one.
1486 The short answer to the question is no. Org-mode adheres to the
1487 cascading logic of outlines, in which a section is closed only by
1488 another section that occupies an equal or greater level.
1490 Here are some workarounds:
1492 1. You can use inline tasks to create non-folding subsections. See the
1493 documentation in org-inlinetask.el, which is part of the org-mode
1495 2. You can create a temporary heading, such as "** Continue main
1496 section" and then remove it when you are ready to export.
1497 3. You can create a separate outline heading (e.g., * ACTIONS),
1498 creating TODOs there with links to the relevant sections of your
1501 ** Can I add a TODO to a list item?
1503 :CUSTOM_ID: list-item-as-todo
1506 No. When generating agenda views, org-mode treats only headlines as TODO
1509 You can, however, use a status cookie together with checkboxes to
1510 monitor your progress on a series of subtasks:
1513 ,** TODO Big task [1/3]
1520 If you would like to embed a TODO within text without treating it as
1521 an outline heading, you can use inline tasks. Simply add...
1523 : (require 'org-inlinetask)
1525 ...to your =.emacs= and then type =C-c C-x t= to insert an inline task.
1527 ** Can I have two windows on the same Org-mode file, with different outline visibilities?
1529 :CUSTOM_ID: indirect-buffers
1532 You may use /indirect buffers/ which do exactly this. See the
1533 documentation on the command =make-indirect-buffer=.
1535 Org-mode has built-in commands that allow you create an indirect
1536 buffer from a subtree of an outline. To open a subtree in new
1537 window, type =C-c C-x b=. Any changes you make in the new window
1538 will be saved to the original file, but the visibility of both
1539 buffers will remain independent of one another.
1541 For multiple indirect buffers from the same file, you must use the
1542 prefix =C-u= when creating the second (or third) buffer. Otherwise
1543 the new indirect buffer will replace the old.
1545 You can also create an independent view of an outline subtree by
1546 typing =b= on an item in the agenda.
1548 ** Emacs outlines are unreadable. Can I get rid of all those stars?
1550 :CUSTOM_ID: Emacs-outlines-are-unreadable
1553 See the section [[https://orgmode.org/manual/Clean-view.html#Clean-view][Clean outline view]] in the manual.
1555 ** C-k is killing whole subtrees! I lost my work!
1557 :CUSTOM_ID: C-k-is-killing-subtrees
1560 =(setq org-ctrl-k-protect-subtree t)= before losing your work.
1562 =(setq org-catch-invisible-edits 'show)= will also be helpful. See the
1563 docstring of this option, as it allows more flexible options.
1565 ** Why aren't commands working on regions?
1567 :CUSTOM_ID: transient-mark-mode
1570 Some org-mode commands, such as M-right and M-left for demoting or
1571 promoting headlines (see [[#demote-multiple-headlines][this FAQ]]), can be applied to entire
1572 regions. These commands, however, will only work on active regions set
1573 with [[http://www.gnu.org/software/emacs/manual/html_node/emacs/Transient-Mark.html#Transient-Mark][transient mark mode]]. Transient mark mode is enabled by default in
1574 Emacs 23. To enable it in earlier versions of emacs, put the following in
1577 : (transient-mark-mode 1)
1579 Alternatively, you may turn off transient mark mode and use [[http://www.gnu.org/software/emacs/manual/html_node/emacs/Momentary-Mark.html][a momentary
1580 mark]] (=C-<SPC> C-<SPC>=).
1582 ** Why is a blank line inserted after headlines and list items?
1584 :ID: 2463F4D8-F686-4CF3-AA07-08976F8A4972
1585 :CUSTOM_ID: blank-line-after-headlines-and-list-items
1590 In org-mode, typing =M-RET= at the end of a headline will create a new
1591 headline of the same level on a new line. The same is true for plain
1592 lists. By default org-mode uses context to determine if a blank line should
1593 be inserted after each headline or plain list item when =M-RET= is
1594 pressed. For instance, if a there is a blank line before a headline, then
1595 typing =M-RET= at the end of the line will insert a blank line before the
1596 new headline. For instance, hitting =M-RET= at the end of "Headline Two"
1597 below inserts a new headline without a blank line:
1603 If there is a blank line between Headline One and Headline Two,
1604 however, the results will be as follows:
1612 If you do not like the default behavior you can change it with the
1613 variable =org-blank-before-new-entry=. You can set headings and/or
1614 plain lists to auto (the default setting), t (always), or nil (never).
1616 ** How can I promote or demote multiple headlines at once?
1618 :CUSTOM_ID: demote-multiple-headlines
1621 #+index: Promote!Multiple
1622 #+index: Demote!Multiple
1624 If you have a long list of first level headlines that you'd like to
1625 demote to second level headlines, you can select the headlines as a
1626 region and then hit =M-<right>= to demote all the headlines at once.
1628 Note: =M-S-<right>= will not work on a selected region. Its use is to
1629 demote a single subtree (i.e., a headline and all sub-headlines).
1631 If M-<right> doesn't seem to work, make sure transient mark mode is
1632 enabled. See [[#transient-mark-mode][this FAQ]].
1634 ** What's the deal with all the ellipses in my org outlines?
1636 :CUSTOM_ID: org-ellipses
1641 Org-mode uses ellipses to indicate folded (and thus hidden) text. Most
1642 commonly, ellispes occur at the end of headings with folded content:
1646 Or, for instance, they may indicate closed drawers:
1650 Sometimes, as a result of editing and cycling an outline, ellipses may
1651 appear in unexpected places. You should *never* delete these ellipses,
1652 as you may accidentally delete hidden text. Instead, you can type =C-c
1653 C-r= (org-reveal) to display all hidden text in the vicinity. Or you
1654 may type =M-x RET show-all= to reveal all text in the org file.
1656 If you would prefer a symbol or face for indicating hidden text, you
1657 can customize the variable org-ellipses.
1659 ** How do I yank a subtree so it's indented according to the point's location?
1661 :CUSTOM_ID: yank-indent-subtree
1664 #+index: Indentation
1666 You can either use =C-c C-w= with a working [[https://orgmode.org/manual/Refile-and-copy.html#Refile-and-copy][refile-targets]] setup.
1668 Or set =org-yank-adjusted-subtrees= to =t= which will adjust the
1669 yanked headline's level correctly.
1671 Just use =C-k= and =C-y= as you would everywhere else in Emacs.
1673 ** Can I read org-mode outlines in vim?
1675 :CUSTOM_ID: org-outlines-in-vim
1680 Yes, there is a script that enables one to view and navigate folded
1681 outline/org files in vim (though without most of org-mode's
1682 functionality, of course).
1684 - [[http://www.vim.org/scripts/script.php?script_id%3D1266][Emacs outline mode - Imitates Emacsen : vim online]]
1686 For instructions on how to set it up, please see [[http://orgmode.org/list/EA275862-B97A-4BAC-B879-177FD07A2D56@gaillourdet.net][this mailing list post]].
1688 Work is also underway on an org-mode clone for Vim. You can check it
1691 https://github.com/hsitz/VimOrganizer
1693 ** Can I use another character than "*" to start a headline?
1695 No. The "*" character is used in =outline-mode=, and Org is derived from
1698 If you are curious as to what other rationales there are for "*", check out
1699 [[https://orgmode.org/list/8739i7ke8i.fsf@gmail.com][this]] mail and the thread it is in.
1701 Even if you cannot use another character, you can add an overlay on top of
1702 the "*" characters and your buffer will look like the way you want.
1704 See the library =org-bullets.el= (by Evgeni Sabof) from the =contrib/=
1705 directory, or test this snippet shared by Jambunathan:
1707 #+BEGIN_SRC emacs-lisp
1708 (font-lock-add-keywords
1709 'org-mode `(("\\(?:^\\(?1:\\*+\\)[[:blank:]]\\)"
1710 (0 (progn (compose-region
1711 (match-beginning 1) (match-end 1)
1712 (pcase (length (match-string 1))
1722 :CUSTOM_ID: Todos-and-Tags
1724 ** How can I automatically archive canceled tasks?
1726 #+BEGIN_SRC emacs-lisp
1727 (setq org-todo-state-tags-triggers '(("CANCELLED" ("ARCHIVE" . t))))
1730 See https://orgmode.org/list/2013-01-18T11-28-57@devnull.Karl-Voit.at -- thanks to Victor
1731 Rosenfeld for sharing [[http://doc.norang.ca/org-mode.html][Bernt Hansen]]'s solution.
1733 ** How can I cycle through the TODO keyword of an entry?
1735 :CUSTOM_ID: cycle-TODO-keywords
1738 #+index: Cycling!Todo
1740 =C-c C-t= or =S-<left/right>= is what you need.
1742 ** How do I track state changes for tasks in Org?
1744 :CUSTOM_ID: track-state-changes-for-tasks
1749 Take a look at the [[https://orgmode.org/list/8763vfa9hl.fsf@legolas.norang.ca][post by Bernt Hansen]] for setting up TODO keyword
1750 states and logging timestamps for task state changes.
1752 ** Can I select the TODO keywords with a tag-like interface?
1754 :CUSTOM_ID: select-TODO-keywords-with-tag-like-interface
1757 #+index: Tag!Fast selection
1759 Yes. Use =(setq org-use-fast-todo-selection t)=
1761 If you want to set both your todos and your tags using a single
1762 interface, then check out the variable
1763 =org-fast-tag-selection-include-todo=.
1765 See [[https://orgmode.org/manual/Fast-access-to-TODO-states.html][this section of the manual]] for more details.
1767 ** How can I quickly set the tag of an entry?
1769 :CUSTOM_ID: quickly-set-tag-of-entry
1774 Use =C-c C-c= or =C-c C-q= on the headline. =C-c C-q= is useful for
1775 setting tabs in a =Remember= buffer, since =C-c C-c= is the default
1776 keybinding for filing a note from the remember buffer.
1778 You can set tags even more quickly by setting one of the character
1779 shortcuts for [[https://orgmode.org/manual/Setting-tags.html#Setting-tags][fast tag selection]].
1781 To set tag shortcuts for all org buffers, put something like the
1782 following in your =.emacs= file (or create the same settings by
1783 typing =M-x customize-variable RET org-tag-alist=):
1785 : (setq org-tag-alist '(("computer" . ?c) ("office" . ?o) ("home" . ?h)))
1787 To set tag shortcuts for a single buffer, put something like the
1788 following at the top of your org file:
1790 : #+TAGS: computer(c) office(o) home(h)
1792 ** How can I change the colors of TODO keywords?
1796 You can use the variable =org-todo-keyword-faces=. Here are some sample
1799 #+begin_src emacs-lisp
1800 (setq org-todo-keyword-faces
1802 ("TODO" . (:foreground "firebrick2" :weight bold))
1803 ("WAITING" . (:foreground "olivedrab" :weight bold))
1804 ("LATER" . (:foreground "sienna" :weight bold))
1805 ("PROJECT" . (:foreground "steelblue" :weight bold))
1806 ("DONE" . (:foreground "forestgreen" :weight bold))
1807 ("MAYBE" . (:foreground "dimgrey" :weight bold))
1808 ("CANCELED" . shadow)
1812 If you want to change the color of all active todos or all inactive todos,
1815 : M-x customize-face RET org-todo
1816 : M-x customize-face RET org-done
1818 You can also set values for each of these in your =.emacs= file:
1820 : (set-face-foreground 'org-todo "firebrick2")
1821 : (set-face-foreground 'org-done "forestgreen")
1823 ** Can I use a arbitrary character in a TODO keyword?
1825 Yes, provided you add it to the "word" syntax in Emacs.
1827 For example, to add the =\u25b6= and the =\u25b8= chars, just add this to
1828 your Emacs configuration:
1830 #+begin_src emacs-lisp
1831 (add-hook 'org-mode-hook
1833 (modify-syntax-entry (string-to-char "\u25b6") "w")
1834 (modify-syntax-entry (string-to-char "\u25b8") "w")))
1837 ** How do I arrange for an item to be automatically marked DONE when all checkboxes are checked?
1841 This has arisen a couple of time
1842 (e.g. https://orgmode.org/list/87r5718ytv.fsf@sputnik.localhost and
1843 https://orgmode.org/list/m2d3efqkl0.fsf@pluto.luannocracy.com in the mailing list.
1845 There is an [[https://orgmode.org/worg/org-hacks.html#mark-done-when-all-checkboxes-checked][org-hack]] that describes a possible solution.
1849 :CUSTOM_ID: Hyperlinks
1852 ** Why do I have to confirm the execution of each shell/elisp link?
1854 :CUSTOM_ID: confirm-shell/elisp-link
1860 The confirmation is there to protect you from unwantingly execute
1861 potentially dangerous commands. For example, imagine a link
1863 : [[shell:rm -rf ~/*][Google Search]]
1865 In an Org-mode buffer, this command would look like /Google Search/,
1866 but really it would remove your home directory. If you wish, you can
1867 make it easier to respond to the query by setting
1869 : (setq org-confirm-shell-link-function 'y-or-n-p
1870 : org-confirm-elisp-link-function 'y-or-n-p).
1872 Then a single keypress will be enough to confirm those links. It is
1873 also possible to turn off this check entirely, but I strongly
1874 recommend against this. Be warned.
1876 ** Can I use RET or TAB to follow a link?
1878 :CUSTOM_ID: RET-or-TAB-to-follow-link
1881 #+index: Link!Follow
1885 : (setq org-return-follows-link t)
1886 : (setq org-tab-follows-link t)
1888 ** Can I keep mouse-1 clicks from following a link?
1890 :CUSTOM_ID: mouse-1-following-link
1893 Activating links with =mouse-1= is a new feature in Emacs 22, to make
1894 link behavior similar to other applications like web browsers. If
1895 you hold the mouse button down a bit longer, the cursor will be set
1896 without following the link. If you cannot get used to this behavior,
1897 you can (as in Emacs 21) use =mouse-2= to follow links and turn off
1898 link activation for =mouse-1= with
1900 : (setq org-mouse-1-follows-link nil)
1902 ** How can I get completion of file names when creating a link?
1904 :CUSTOM_ID: completion-of-file-links
1907 #+index: Link!Completion
1909 You can use org-insert-link with a prefix argument:
1913 You will be greeted with prompt in the minibuffer that allows for file
1914 completion using your preferred Emacs method for finding files.
1916 ** How can I use invisible targets within lists?
1918 :CUSTOM_ID: invisible-targets-in-lists
1921 #+index: Target!Invisible
1923 The usual way of turning radio links invisible is to comment them, but
1924 Org comments need to be at the beginning of the line, which breaks list
1927 The workaround here is to add (INVISIBLE) after your <<target>>
1931 : 11. <<target>>(INVISIBLE)
1933 : 12. More text [[target][go to]]
1935 ** Org-mode is not opening mailto links in my default mail client
1937 :CUSTOM_ID: mailto-links
1940 #+index: Link!Mailto
1942 You can customize the function org-mode uses to open mailto links by
1943 setting the variable =org-link-mailto-program=:
1945 =M-x customize-variable org-link-mailto-program=
1947 The default function called is =browse-url=, which opens a mail
1948 composition buffer within Emacs. The type of buffer opened by
1949 browse-url depends on the setting of the variable =mail-user-agent=.
1950 Thus, if you want to ensure that mailto links use Gnus to open a
1951 message buffer, you could add the following to your =.emacs=:
1954 (setq mail-user-agent 'gnus-user-agent)
1957 ** Can I use CamelCase links?
1959 :CUSTOM_ID: CamelCase-links
1962 #+index: Link!CamelCase
1964 Yes, you can with the contributed package =org-wikinodes.el=. Please
1965 consult the [[https://orgmode.org/worg/org-contrib/org-wikinodes.html][documentation]].
1967 ** Can I create links to Thunderbirds emails?
1969 Yes, see this: [[http://orgmode.org/list/ka42mn$mn9$1@ger.gmane.org][from Christoph Herzog: Re: Linking to Thunderbird (correction)]]
1971 #+BEGIN_SRC emacs-lisp
1974 (org-add-link-type "thunderlink" 'org-thunderlink-open)
1976 (defun org-thunderlink-open (path)
1977 "Opens an email in Thunderbird with ThunderLink."
1978 (start-process "myname" nil "thunderbird" "-thunderlink" (concat "thunderlink:" path)))
1980 (provide 'org-thunderlink)
1985 :CUSTOM_ID: Plain-Lists
1988 ** How can I insert an empty line before each newly inserted headline, but not before each newly inserted plain-list item?
1990 :CUSTOM_ID: empty-line-before-each-new-headline-but-not-item
1993 : (setq org-blank-before-new-entry
1994 : '((heading . t) (plain-list-item . nil))
1996 See also [[id:2463F4D8-F686-4CF3-AA07-08976F8A4972][Why is a blank line inserted after headlines and list items?]].
1998 ** How can I convert itemized lists to enumerated lists?
2000 :CUSTOM_ID: convert-itemized-to-enumerated-lists
2003 #+index: List!Itemized
2004 #+index: List!Enumerated
2006 You can use =C-c -= or =S-<left>/<right>= to cycle through the various
2007 bullet headlines available for lists: =-, +, *, 1., 1)=.
2009 See [[https://orgmode.org/manual/Plain-lists.html#Plain-lists][this section of the manual]] for more information.
2011 ** How can I convert plain lists to headlines and vice versa?
2013 :CUSTOM_ID: convert-plain-lists-to-headlines
2019 To convert a plain list item or line to a headline, type =C-c *= on
2020 the headline. This will make the line a subheading of the current
2023 To convert a headline to a plain list item, type =C-c -= while the
2024 cursor is on the headline.
2026 To convert a headline to an unadorned line of text, type =C-c *= on
2029 You can use query replace to accomplish the same things, as Bernt
2030 Hansen explains in [[https://orgmode.org/list/871vvrym45.fsf@gollum.intra.norang.ca][this mailing list post]].
2032 ** Is there a good way to create a description list?
2034 :CUSTOM_ID: description-lists
2037 #+index: List!Description
2039 Yes, these are now built-in:
2042 - item1 :: Description of this item 1
2043 - item2 :: Description of this item 2
2044 - item1 :: Description of this item 3
2045 also in multiple lines
2048 ** How can I export alphabetical lists to... alphabetical lists?
2050 =org-list-allow-alphabetical= allows you to use alphabetical lists in
2051 Org, but this is purely visual, there is no effect on how the list is
2052 exported. It is simply exported as an /ordered/ list, just like when
2053 you use numberes. How the list will be represented in the export
2054 depends on the backend. For example, the style file of a LaTeX
2055 document, or the CSS file for HTML documents set how ordered lists
2056 should be represented. It is good style to adhere to these general
2057 settings because it keeps the overall document structure consistent.
2059 See [[http://orgmode.org/list/87mwq6qtjk.fsf@gmail.com][this thread]] (and earlier ones) for a discussion about this.
2066 ** Will there ever be support for multiple lines in a table field?
2068 :CUSTOM_ID: table-multiline-fields
2073 You can embed tables created with the =table.el= package in org-mode
2074 buffers, with mixed success when it comes to export and publishing.
2076 ** How can I make table alignment work with Asian character sets
2078 :CUSTOM_ID: table-alignment-asian-characters
2081 #+index: Table!Alignment
2083 When table alignment fails, it usually has to do with character sets
2084 where some characters have non-integer width. Org will deal correctly
2085 with characters that are one or two or three ASCII characters wide,
2086 but not with characters that are, for example, 1.5 ASCII characters
2087 wide. To make table alignment work you need to switch to a different
2090 ** Can I plot data from a table?
2092 :CUSTOM_ID: plotting-table-data
2099 Yes, you can, using org-plot.el written by Eric Schulte and now
2100 bundled with Org. See [[https://orgmode.org/manual/Org_002dPlot.html#Org-Plot][the manual section about this]].
2102 See also [[file:org-tutorials/org-plot.org][this excellent tutorial]] by Eric Schulte.
2104 ** How can I fill a table column with incremental numbers?
2106 :CUSTOM_ID: fill-table-column-with-incremental-numbers
2111 Here is how: Use a field formula to set the first value in the column:
2123 Then define a column formula in the second field:
2135 After recomputing the table, the column will be filled with
2136 incremental numbers:
2145 ,#+TBLFM: $1=@-1 + 1::@2$1=1
2148 Note that you could use arbitrary starting values and column formulas.
2150 Alternatively, you can just start the table
2158 and with the cursor on the 1, use S-RET (bound to org-table-copy-down). That
2159 will add a row, incrementing the number as it goes. See the docstring for org-table-copy-down
2160 for more information and also see the next FAQ entry [[=S-RET= in a table keeps increasing the copied numbers. How can I stop this?]]
2161 if you don't want this behavior.
2163 ** =S-RET= in a table keeps increasing the copied numbers. How can I stop this?
2165 :CUSTOM_ID: S-RET-in-a-table-increases-copied-numbers
2168 Well, it is /supposed/ to be a feature, to make it easy to create a
2169 column with increasing numbers. If this gets into your way, turn it
2172 : (setq org-table-copy-increment nil)
2174 ** Why does my table column get filled with #ERROR?
2176 :CUSTOM_ID: table-column-filled-with-ERROR
2179 #+index: Table!#ERROR
2181 Org-mode tried to compute the column from other fields using a
2182 formula stored in the =#+TBLFM:= line just below the table, and
2183 the evaluation of the formula fails. Fix the fields used in the
2184 formula, or fix the formula, or remove it!
2186 ** How can I stop the table editor from creating new lines?
2188 :CUSTOM_ID: table-editor-creates-new-lines
2191 When I am in the last column of a table and just above a horizontal
2192 line in the table, pressing TAB creates a new table line before the
2193 horizontal line. To move to the line below the
2194 horizontal line instead, do this:
2196 Press =down= (to get on the separator line) and then =TAB=.
2197 Or configure the variable
2199 : (setq org-table-tab-jumps-over-hlines t)
2201 ** How can I get table fields starting with "="?
2203 :CUSTOM_ID: table-fields-starting-with-=
2208 : (setq org-table-formula-evaluate-inline nil)
2210 this will no longer happen. You can still use formulas using the
2211 commands ~C-c =~ and ~C-u C-c =~
2213 ** How can I get a vertical bar "|" inside a table field?
2215 :CUSTOM_ID: table-fields-with-vertical-bar
2218 You can use =\vert= to put a vertical bar inside a table field. This
2219 will be converted for export. To use it inside a word use
2220 =abc\vert{}def=. If you need something that looks like a bar in the Org
2221 mode buffer, you can use the unicode character brvbar which looks like
2224 ** How can I change the indentation of an entire table without fixing every line by hand?
2226 :CUSTOM_ID: change-indentation-entire-table
2229 #+index: Table!Indentation
2231 The indentation of a table is set by the first line. So just fix the
2232 indentation of the first line and realign with =TAB=.
2234 ** In my huge table the realigning after each TAB takes too long. What can I do?
2236 :CUSTOM_ID: table-realigning-after-TAB-takes-long
2239 #+index: Table!Realign
2241 Either split the table into several by inserting an empty line every
2242 100 lines or so. Or turn off the automatic re-align with
2244 : (setq org-table-automatic-realign nil)
2246 After this the only way to realign a table is to press =C-c C-c=. It
2247 will no longer happen automatically, removing the corresponding delays
2250 ** Recalculation of my table takes too long. What can I do?
2252 :CUSTOM_ID: Recalculation-of-my-table-takes-too-long
2255 #+index: Table!Calculation
2257 Nothing, really. The spreadsheet in org is mostly done to make
2258 calculations possible, not so much to make them fast. Since Org-mode is
2259 firmly committed to the ASCII format, nothing is stopping you from
2260 editing the table by hand. Therefore, there is no internal
2261 representation of the data. Each time Org-mode starts a computation, it
2262 must scan the table for special lines, find the fields etc. This is
2263 slow. Furthermore, Calc is slow compared to hardware computations. To
2264 make this work with normal editing, recalculation is not happening
2265 automatically, or only for the current line, so that the long wait for a
2266 full table iteration only happens when you ask for it.
2268 So for really complex tables, moving to a "real" spreadsheet may
2269 still be the best option.
2271 That said, there are some ways to optimize things in Org-mode, and I
2272 have been thinking about moving a bit further down this line.
2273 However, for my applications this has so far not been an issue at
2274 all. If you have a good case, you could try to convince me.
2276 ** When I export tables to HTML, they don't have borders.
2278 :CUSTOM_ID: table-borders-in-html-export
2283 By default, Org-mode exports tables without borders.
2285 You can changed this by placing an =#+ATTR_HTML= line before the table:
2287 : #+ATTR_HTML: :border 2 :rules all :frame all
2289 See [[https://orgmode.org/manual/Tables-in-HTML-export.html#Tables-in-HTML-export][the manual]] for more details.
2291 ** Why does the Calc high precision (e. g. =p20=) not work like expected?
2293 :CUSTOM_ID: table-high-precision
2299 : | 1 / 2 * 3 | 0.16666667000000 |
2300 : #+TBLFM: $2 = $1; p20 %.14f
2303 : | 1 / 2 * 3 | 0.16666666666667 |
2304 : #+TBLFM: $2 = $1 +.0; p20 f-14
2308 It is important to distinguish between the precision of
2309 1) =p20=: Calc internal calculation (=calc-internal-prec=)
2310 2) =f-14=: Calc float formatting, unlimited in precision (=calc-float-format=)
2311 3) =%.14f=: the =printf= reformatting, limited in precision
2313 See [[https://orgmode.org/manual/Formula-syntax-for-Calc.html#Formula-syntax-for-Calc][the Org manual]] (org-version 6.35 or newer) for more details.
2315 Use =C-h v org-calc-default-modes RET= to check the Org default settings
2316 which are used if no format specifiers are added to a table formula.
2317 The examples below have been made with the out_of_the_box Org defaults
2318 =calc-internal-prec = 12= and =calc-float-format = 8=.
2320 Remember the formula debugger, toggled with =C-c {=,
2321 to view the processing stages like:
2322 | | formula debugger label | processing stage |
2324 |---+------------------------+----------------------------|
2325 | | Result: | output of Calc |
2326 | | Format: | reformatting with =printf= |
2328 Following are some examples to demonstrate
2329 the interaction of the three precisions.
2331 - *display precision limitations for Calc formulas*
2332 - limited by Calc internal calculation precision from Org default
2334 : | 0.16666666666700 |
2335 : #+TBLFM: $1 = 1 / 2 * 3; f-14
2337 : | 0.1666666666670000000 |
2338 : #+TBLFM: $1 = 1 / 2 * 3; f-19
2340 - limited by Calc float format from Org default (here =f8=)
2342 : #+TBLFM: $1 = 1 / 2 * 3
2345 : #+TBLFM: $1 = 1 / 2 * 3; p20
2347 : | 0.16666667000000 |
2348 : #+TBLFM: $1 = 1 / 2 * 3; %.14f
2350 : | 0.16666667000000 |
2351 : #+TBLFM: $1 = 1 / 2 * 3; p20 %.14f
2353 - limited by Calc float format specified
2355 : #+TBLFM: $1 = 1 / 2 * 3; f-6
2357 : | 0.16666666666667 |
2358 : #+TBLFM: $1 = 1 / 2 * 3; p20 f-14
2360 : | 0.1666666666666666667 |
2361 : #+TBLFM: $1 = 1 / 2 * 3; p20 f-19
2363 - limited by =printf= conversion to Emacs Lisp float
2364 : | 0.1666666699999999900 | the inaccuracy is platform dependent |
2365 : #+TBLFM: $1 = 1 / 2 * 3; %.19f
2367 : | 0.1666666699999999900 | the inaccuracy is platform dependent |
2368 : #+TBLFM: $1 = 1 / 2 * 3; p20 %.19f
2370 : | 0.1666666666666666600 | the inaccuracy is platform dependent |
2371 : #+TBLFM: $1 = 1 / 2 * 3; p20 f-20 %.19f
2373 - limited by =printf= format specified
2375 : #+TBLFM: $1 = 1 / 2 * 3; %.6f
2377 - *display precision limitations for Emacs Lisp formulas*
2378 - limited by Emacs Lisp float
2379 : | 0.16666666666666666 |
2380 : #+TBLFM: $1 = '(/ 1.0 (* 2 3))
2382 : | 0.1666666666666666574 | the inaccuracy is platform dependent |
2383 : #+TBLFM: $1 = '(/ 1.0 (* 2 3)); %.19f
2385 - limited by =printf= format specified
2386 : | 0.16666666666667 |
2387 : #+TBLFM: $1 = '(/ 1.0 (* 2 3)); %.14f
2389 This FAQ entry is based on this [[https://orgmode.org/list/4B882C11.90406@alumni.ethz.ch][mailing list thread]]
2390 and is continued in the [[#table-float-fraction][next FAQ entry]].
2392 ** Which float format shows the fraction part also when the latter is zero?
2394 :CUSTOM_ID: table-float-fraction
2401 : #+TBLFM: $2 = $1; f-3
2404 : #+TBLFM: $2 = $1 +.0; f-3
2408 For =f3= and =f-3= see =`d f' (`calc-fix-notation')= in [[http://www.delorie.com/gnu/docs/calc/calc.html#SEC_Top][the Calc manual]]
2409 in the section Mode Settings -> Display Modes -> Float Formats
2410 [[http://www.delorie.com/gnu/docs/calc/calc_163.html][found here as long as the section numbering is unchanged]].
2412 Remember the formula debugger, toggled with =C-c {=,
2413 to view the processing stages like:
2414 | | formula debugger label | processing stage |
2416 |---+------------------------+----------------------------|
2417 | | Result: | output of Calc |
2418 | | Format: | reformatting with =printf= |
2420 Following are some examples to demonstrate different float formats.
2423 : |-----------+---------+-------+---------+----------+-------|
2424 : | number | f3 | f-3 | +.0; f3 | +.0; f-3 | %.3f |
2425 : |-----------+---------+-------+---------+----------+-------|
2426 : | 1 | 1 | 1 | 1.000 | 1.000 | 1.000 |
2427 : | 0 | 0 | 0 | 0.000 | 0.000 | 0.000 |
2428 : |-----------+---------+-------+---------+----------+-------|
2429 : | 1.0 | 1.000 | 1.000 | 1.000 | 1.000 | 1.000 |
2430 : | 0.0 | 0.000 | 0.000 | 0.000 | 0.000 | 0.000 |
2431 : |-----------+---------+-------+---------+----------+-------|
2432 : | 1.0001666 | 1.000 | 1.000 | 1.000 | 1.000 | 1.000 |
2433 : | 0.0001666 | 1.67e-4 | 0.000 | 1.67e-4 | 0.000 | 0.000 |
2434 : |-----------+---------+-------+---------+----------+-------|
2435 : | 1.0016666 | 1.002 | 1.002 | 1.002 | 1.002 | 1.002 |
2436 : | 0.0016666 | 0.002 | 0.002 | 0.002 | 0.002 | 0.002 |
2437 : |-----------+---------+-------+---------+----------+-------|
2438 : #+TBLFM: $2 = $1; f3 :: $3 = $1; f-3 :: $4 = $1 +.0; f3 :: $5 = $1 +.0; f-3 :: $6 = $1; %.3f
2441 : |----------------------+--------------------------+-----------------------|
2442 : | number | f19 | f-19 |
2443 : |----------------------+--------------------------+-----------------------|
2446 : |----------------------+--------------------------+-----------------------|
2447 : | 1.0 | 1.0000000000000000000 | 1.0000000000000000000 |
2448 : | 0.0 | 0.0000000000000000000 | 0.0000000000000000000 |
2449 : |----------------------+--------------------------+-----------------------|
2450 : | 1 + 1 / 2 * 3 * 1e19 | 1.0000000000000000000 | 1.0000000000000000000 |
2451 : | 0 + 1 / 2 * 3 * 1e19 | 1.666666666666666667e-20 | 0.0000000000000000000 |
2452 : |----------------------+--------------------------+-----------------------|
2453 : | 1 + 1 / 2 * 3 * 1e18 | 1.0000000000000000002 | 1.0000000000000000002 |
2454 : | 0 + 1 / 2 * 3 * 1e18 | 0.0000000000000000002 | 0.0000000000000000002 |
2455 : |----------------------+--------------------------+-----------------------|
2456 : #+TBLFM: $2 = $1; p20 f19 :: $3 = $1; p20 f-19
2458 : |----------------------+--------------------------+-----------------------|
2459 : | number | +.0; f19 | +.0; f-19 |
2460 : |----------------------+--------------------------+-----------------------|
2461 : | 1 | 1.0000000000000000000 | 1.0000000000000000000 |
2462 : | 0 | 0.0000000000000000000 | 0.0000000000000000000 |
2463 : |----------------------+--------------------------+-----------------------|
2464 : | 1.0 | 1.0000000000000000000 | 1.0000000000000000000 |
2465 : | 0.0 | 0.0000000000000000000 | 0.0000000000000000000 |
2466 : |----------------------+--------------------------+-----------------------|
2467 : | 1 + 1 / 2 * 3 * 1e19 | 1.0000000000000000000 | 1.0000000000000000000 |
2468 : | 0 + 1 / 2 * 3 * 1e19 | 1.666666666666666667e-20 | 0.0000000000000000000 |
2469 : |----------------------+--------------------------+-----------------------|
2470 : | 1 + 1 / 2 * 3 * 1e18 | 1.0000000000000000002 | 1.0000000000000000002 |
2471 : | 0 + 1 / 2 * 3 * 1e18 | 0.0000000000000000002 | 0.0000000000000000002 |
2472 : |----------------------+--------------------------+-----------------------|
2473 : #+TBLFM: $2 = $1 +.0; p20 f19 :: $3 = $1 +.0; p20 f-19
2475 The =printf= reformatting (=%.19f=) cannot be used with high precision,
2476 see the [[#table-high-precision][previous FAQ entry]].
2478 ** How can I center tables in LaTeX output?
2480 :CATEGORY: centered-tables-in-latex
2483 #+index: Table!Center
2485 Set the `org-latex-tables-centered' to `t':
2487 : (defcustom org-latex-tables-centered t
2488 : "When non-nil, tables are exported in a center environment."
2489 : :group 'org-export-latex
2492 ** Can I exclude columns from a table when exporting it?
2498 :CUSTOM_ID: Footnotes
2500 ** How can I get automatic renumbering of footnotes in org-mode?
2502 :CUSTOM_ID: footnote-auto-adjust
2505 #+index: Footnotes!Renumbering
2507 You can add the following line to your .emacs file:
2509 : (setq org-footnote-auto-adjust t)
2511 Or, if you prefer, you can turn this option on locally by placing the
2512 following line at the top of your org file:
2514 : #+STARTUP: fnadjust
2516 When auto-adjust is turned on, footnotes in the file with numerical
2517 labels will be renumbered whenever a new footnote is added. Meanwhile,
2518 all footnotes, including those with custom labels such
2519 =[fn:custom-label ]=, will be sorted in the order of their appearance
2522 This emulates the footnote behavior that many users may be familiar
2523 with from word-processing programs or from the footnote-mode included
2526 If you do not turn on org-footnote-auto-adjust, you sort and/or
2527 renumber footnotes at any time by calling org-footnote-action with a
2530 ** Why isn't auto renumbering of footnotes turned on by default?
2532 :CUSTOM_ID: why-no-default-auto-adjust
2535 Org-mode has a very robust footnote mechanism allowing for a variety of
2536 types of footnotes. With some of the following footnote notations,
2537 auto-adjust may be either irrelevant or undesired:
2539 - Automatically numbered
2540 - Footnotes with custom labels
2543 In addition, Org-mode can be customized to place footnotes either at
2544 the end of a document or at the end of the outline heading in which
2545 they appear. Users who change this setting while editing a document
2546 may be disconcerted to find all of their footnotes rearranged
2549 ** I have auto-fill-mode set and org-mode is inserting unwanted comment markers!
2551 :CUSTOM_ID: auto-fill-and-unwanted-comments
2554 If the following occurs:
2559 ,# More entered tex.
2562 Make sure that the variable comment-start is nil.
2564 ** Are there any shortcuts for entering source blocks and comment lines?
2566 :CUSTOM_ID: shortcuts-for-entering-source-blocks
2569 Org-mode has some [[https://orgmode.org/manual/Literal-examples.html#Literal-examples][very convenient markup]] for including literal blocks and
2570 lines of code in a file. (This is especially useful when exporting
2571 documents or using the contributed package [[file:org-contrib/babel/index.org][org-babel]] for executing blocks
2576 print "Hello, world!\n";
2580 It can be tiresome to enter the block comment lines manually. There are
2581 several possible shortcuts you can use to enter them:
2583 1) Built-in expansion
2585 - Org-mode has a "secret" method of expanding source code blocks
2588 - If you type "<s" followed by =TAB= or =M-TAB=, a source block will
2591 - For a full list of expansions, type =M-x describe-variable
2592 [RET] org-structure-template-alist=.
2594 2) [[https://orgmode.org/manual/Literal-examples.html#Literal-examples][Registers]]
2596 - Add the following line to your emacs file:
2598 =(set-register ?p "#+begin_src\n\n#+end_src perl")=
2600 - Then type =C-x r i p= to insert the source block. Please note: if
2601 you save another value to the register "p" with =C-x r s p=, it
2602 will overwrite the setting above for the current emacs session.
2604 3) [[https://orgmode.org/manual/Literal-examples.html#Literal-examples][Abbrevs]]
2606 - Activate the abbrev minor-mode in org-mode:
2612 + =(add-hook 'org-mode-hook (lambda () (abbrev-mode 1)))=
2614 - In org-mode, type "sbp" (a sample abbreviation for a perl source
2617 - Immediately after "sbp" type =C-x a i l=.
2619 - Enter the expansion:
2621 - =#+begin_src perl[C-q C-j][C-q C-j]#+end_src=
2623 - Note: =C-q C-j= creates a new line in the minibuffer
2625 - Now, whenever, you type sbp followed by =SPACE= or =RET= in an
2626 org-mode buffer, the src block will magically appear.
2628 - To review your list of abbrevs, type =M-x edit-abbrevs=.
2630 4) [[http://www.emacswiki.org/emacs/SkeletonMode][Skeletons]]
2632 - Skeletons offer a simple way of automatically entering text.
2633 Here's a skeleton that queries for the type of block and wraps
2634 the active region inside it:
2637 (define-skeleton skel-org-block
2638 "Insert an org block, querying for type."
2645 - Simply type skel-org-block to insert the block.
2647 - You can bind this to a key.
2649 - You can also create an abbrev that invokes this function:
2651 : (define-abbrev org-mode-abbrev-table "blk" "" 'skel-org-block)
2653 5) [[http://code.google.com/p/yasnippet/][Yasnippet]]
2655 - Several org-mode users install yasnippet for convenient, complex
2658 - See Bernt Hansen's [[http://doc.norang.ca/org-mode.html#Yasnippets][org-mode setup]] for a good introduction to
2661 * Capture and remember
2663 :CUSTOM_ID: Remember
2666 ** Can I use a variable or a function inside the `org-capture-templates' variable?
2668 :CUSTOM_ID: variable-inside-capture-templates
2673 Yes. Use [[http://www.gnu.org/s/emacs/manual/html_node/elisp/Backquote.html][backquotes]].
2675 E.g. if you have a variable called =org-test-file= and you want the
2676 variable =org-capture-templates= to "understand" (i.e. evaluate)
2677 =org-test-file= when Emacs evaluates the =(setq org-capture-templates
2678 [...])= expression, use backquotes like this:
2680 #+begin_src emacs-lisp
2681 (setq org-capture-templates
2682 `(("t" "Todo" entry (file+headline ,org-test-file "Tasks")
2683 "* TODO %?\n %i\n %a")
2684 ("b" "Buy" item (file+olp ,org-test-file "Stuff to Buy" "House")
2688 ** Can I use the remember buffer to clock a customer phone call?
2690 :CUSTOM_ID: use-remember-buffer-to-clock-phone-call
2693 Yes, you can. Take a look at the [[https://orgmode.org/list/87tzkhoi45.fsf@gollum.intra.norang.ca][setup described by Bernt Hansen]] and
2694 check out (in the same thread) what Nick Docos had to fix to make Bernt's
2695 set-up work for him.
2697 ** Can I automatically start the clock when opening a remember template?
2699 :CUSTOM_ID: start-clock-when-opening-remember-template
2702 #+index: Clock!Start
2704 Yes, this is possible. Use the following code and make sure that
2705 after executing it, `my-start-clock-if-needed' is in
2706 `remember-mode-hook' /after/ `org-remember-apply-template'.
2708 : (add-hook 'remember-mode-hook 'my-start-clock-if-needed 'append)
2709 : (defun my-start-clock-if-needed ()
2711 : (goto-char (point-min))
2712 : (when (re-search-forward " *CLOCK-IN *" nil t)
2713 : (replace-match "")
2716 Then, when a template contains the key string CLOCK-IN, the clock
2717 will be started. Starting with Org-mode version 5.20, the clock will
2718 automatically be stopped when storing the remember buffer.
2722 :CUSTOM_ID: Searches
2725 ** Isearch does not find string hidden in links. What can I do?
2727 :CUSTOM_ID: isearch-in-links
2732 M-x =visible-mode= will display the full link, making them searchable.
2734 ** How can I reduce the amount of context shown in sparse trees?
2736 :CUSTOM_ID: context-in-sparse-trees
2741 Take a look at the following variables:
2743 - =org-show-hierarchy-above=
2744 - =org-show-following-headline=
2745 - =org-show-siblings=
2746 - =org-show-entry-blow=
2748 which give command-dependent control over how much context is shown by a
2749 particular operation.
2751 ** How can I combine the results of two calls to =org-occur=?
2753 :CUSTOM_ID: two-calls-to-org-occur
2758 You can construct a regular expression that matches all targets you
2759 want. Alternatively, use a =C-u= prefix with the second and any
2760 further calls to =org-occur= to keep the current visibility and
2761 highlighting in addition to the new ones.
2768 ** My agenda commands are slow. What to do?
2770 See the dedicated page about [[file:agenda-optimization.org][agenda speed up and optimization]].
2772 ** How can I change the advanced warning time for deadlines?
2774 :CUSTOM_ID: warning-period-for-deadlines
2777 #+index: DEADLINE!Warning
2779 Deadline warnings appear in the daily agenda view a specified number
2780 of days before the deadline is due. The default setting is 14 days.
2781 You can change this with the variable =org-deadline-warning-days=.
2782 (See [[https://orgmode.org/manual/Deadlines-and-scheduling.html#Deadlines-and-scheduling][this section]] of the manual.)
2786 : (setq org-deadline-warning-days 30)
2788 would cause warnings for each deadline to appear 30 days in advance.
2790 Naturally, you might not want warnings for all of your deadlines to
2791 appear so far in advance. Thus, you can change the lead time for
2792 individual items as follows:
2794 : * TODO Get a gift for the party
2795 : DEADLINE: <2009-01-16 Fri -2d>
2797 The "-2d" above changes the lead time for this deadline warning to two
2798 days in advance. You can also use "w" for weeks and "m" for months.
2800 ** How can I postpone a task until a certain date?
2802 :CUSTOM_ID: deferring-tasks
2807 The easiest way to postpone a task is to schedule it in the future. For
2808 instance, typing =C-c C-s +2w= on a headline will push a task two weeks
2809 into the future, so that it won't show up on the daily agenda until two
2812 If you'd like to prevent the task from showing up on your global todo list,
2813 you have a couple of options.
2815 1. You can set the variable =org-agenda-todo-ignore-scheduled= to
2816 =t=. This will exclude any scheduled items from your global list of
2817 active todos (=C-c a t=). (The variable
2818 =org-agenda-todo-ignore-with-date= will exclude both scheduled and
2819 deadline items from your todo list).
2821 2. You can remove the todo keyword from the item (C-c C-t <SPC>). The item
2822 will still appear on your agenda two weeks from today, but it won't show
2823 up on your todo lists.
2825 ** Can I send myself an email containing tasks or other agenda info?
2827 :CUSTOM_ID: email-containing-tasks-or-other-agenda-info
2830 Yes. See [[https://orgmode.org/list/m3ve3d1596.fsf@richardriley.net][this thread]] on the list.
2832 ** How can I limit the agenda view to my "work" tasks?
2834 :CUSTOM_ID: limit-agenda-with-tag-filtering
2839 It is often convenient to group org files into separate categories, such
2840 as "home" and "work" (or "personal" and "professional"). One of the main
2841 reasons for such classification is to create agenda views that are
2842 limited by type of work or area of responsibility. For instance, while
2843 at work, one may want to see only professional tasks; while away from
2844 work, one may want to see only personal tasks.
2846 One way to categorize files and tasks is to use a "#+FILETAGS"
2847 declaration at the top of each file, such as:
2851 As long as org-use-tag-inheritance is turned on, the filetags will
2852 be inherited by all tasks in the file. A file can have multiple
2853 filetags. And, of course, tags can be added to individual headings.
2855 Tasks can be quickly filtered by tag from within the agenda by
2856 typing "/" and the name of the tag. The full key sequence to filter
2857 for work items in an agenda view would be:
2859 : C-c a a / work [or a tag shortcut]
2861 ** How can I limit the agenda view to a particular category?
2863 :CUSTOM_ID: limit-agenda-with-category-match
2866 #+index: Agenda view!Category
2868 Another way to filter agenda views by type of work is to use a
2869 "#+CATEGORY" declaration at the top of each file, such as:
2873 Categories can also be added to individual headings within a file:
2880 All todos belonging to the category "work" can be found a with a
2881 simple tags-todo search:
2885 At the prompt, type:
2889 The same results can be achieved with custom agenda commands, such as:
2891 #+BEGIN_SRC emacs-lisp
2892 (setq org-agenda-custom-commands
2893 '(("h" tags-todo "CATEGORY=\"home\"")
2894 ("w" tags-todo "CATEGORY=\"work\"")
2895 ;; other custom agenda commands here
2899 ** How can include all org files in a directory in my agenda?
2901 :CUSTOM_ID: set-agenda-files-using-wildcards
2904 #+index: Agenda!Directory
2906 You can simply include the directory (as one of the items) in the value of
2907 the variable org-agenda-files:
2909 : (setq org-agenda-files '("/my/special/path/org/"))
2911 There is another way of accomplishing the same end:
2913 : (setq org-agenda-files (file-expand-wildcards "/my/special/path/org/*.org"))
2915 ** Why aren't items disappearing from my agenda once they are marked done?
2917 :CUSTOM_ID: removing-done-items-from-agenda
2920 If items remain on your daily/weekly agenda after they are marked done,
2921 check the configuration of the following variables:
2923 : org-agenda-skip-scheduled-if-done
2924 : org-agenda-skip-deadline-if-done
2925 : org-agenda-skip-timestamp-if-done
2929 : M-x customize-variable RET org-agenda-skip-scheduled-if-done
2931 If this variable is turned off (=nil=), then scheduled items will
2932 remain on the agenda even after they are marked done.
2934 If the variable is turned on (=t=), then scheduled items will
2935 disappear from the agenda after they are marked done.
2937 If these settings seem not to behave the way you expect, then make
2938 sure you understand [[#scheduled-vs-deadline-vs-timestamp][the difference between SCHEDULED, DEADLINE, and
2941 ** How do I keep repeating timestamps from being displayed multiple times?
2943 :CUSTOM_ID: repeating-timestamps-show-once
2946 #+index: Timestamp!Repeating
2948 To show only the /current/ instance of a repeating timestamp, put the
2949 following in your .emacs:
2951 #+begin_src emacs-lisp
2952 (setq org-agenda-repeating-timestamp-show-all nil)
2955 ** What is the difference between SCHEDULED, DEADLINE, and plain timestamps?
2957 :CUSTOM_ID: scheduled-vs-deadline-vs-timestamp
2964 1. SCHEDULED items (set with =C-c C-s=) will appear on your agenda on
2965 the day they are scheduled and on every day thereafter until they
2966 are done. Schedule a task if you want to be reminded to do
2967 something beginning on a certain day and until it is done.
2969 : ** TODO Scheduled item
2970 : SCHEDULED: <2009-03-01 Sun>
2972 2. Items with a DEADLINE timestamp (set with =C-c C-d=) appear on your
2973 agenda in advance of the when they are due and remain on your
2974 agenda until they are done. Add a DEADLINE to an item if you want
2975 to make sure to complete it by a certain date. (The variable
2976 org-deadline-warning-days determines how far in advance items with
2977 deadlines will show up in the agenda. See [[#warning-period-for-deadlines][this FAQ]] for more
2980 : ** TODO Item with a deadline
2981 : DEADLINE: <2009-01-20 Tue>
2983 3. An active timestamp (set with =C-c .=) will appear on your agenda
2984 only on the day it is scheduled. Use a timestamp for appointments
2985 or any reminders you want to show up only on a particular day.
2987 : ** TODO Item with an active timestamp
2990 Note: items with inactive timestamps (set with C-c ! and marked by
2991 square brackets) will not show up in the agenda at all.
2993 ** Can I add files recursively to my list of agenda files?
2995 :CUSTOM_ID: set-agenda-files-recursively
2998 Yes, you can use the library =find-lisp=.
3000 : (load-library "find-lisp")
3001 : (setq org-agenda-files (find-lisp-find-files "~/org" "\.org$"))
3003 This will add all files ending in =org= in the directory "~/org"
3004 and all of its subdirectories to your list of agenda files.
3006 If on a *nix machine, you can also use the find utility, which can be
3007 faster than the find-lisp library:
3009 : (setq org-agenda-files
3010 : (mapcar 'abbreviate-file-name
3012 : (shell-command-to-string "find ~/org -name \"*.org\"") "\n")))
3015 See [[https://orgmode.org/list/7b4bbp$11a9u8@dmzms99802.na.baesystems.com][this thread]] on the mailing list for more information.
3017 ** Why does an item appearing at the wrong time of day in my agenda?
3019 :CUSTOM_ID: agenda-wrong-time-of-day
3022 When preparing the agenda view, org-mode scans each relevant headline for a
3023 time designation. This approach is very nice for adding free-form
3024 timestamps to an item for scheduling. Thus, either of the following work
3025 would work to schedule an item at 10:00am:
3028 ,** 10:00am Get dried ice at the magic store
3029 SCHEDULED: <2009-05-27 Wed>
3033 ,** Get dried ice at the magic store
3034 SCHEDULED: <2009-05-27 Wed 10:00>
3037 To enable this flexibility, org-mode scans the entire headline for time of
3038 day notation. A potential problem can arise if you use inactive timestamps
3039 in the headline to note when an item was created. For example :
3042 ,** Get dried ice at the magic store [2009-05-26 Tue 12:58]
3043 SCHEDULED: <2009-05-27 Wed>
3046 Org-mode would interpret the time in the inactive timestamp as a
3047 time-of-day indicator and the entry would appear in your agenda at
3050 If you would like to turn off the time-of-day search, you can configure the
3051 variable =org-agenda-search-headline-for-time= (requires org-mode >= 6.24).
3053 ** How can I change the visibility of an item from the agenda?
3055 :CUSTOM_ID: cycling-visibility-from-agenda
3058 #+index: Agenda!Visibility
3060 You can add a keybinding as follows:
3062 #+begin_src emacs-lisp
3063 (add-hook 'org-agenda-mode-hook
3065 (define-key org-agenda-mode-map " " 'org-agenda-cycle-show)))
3068 Then, as you press SPACE on an item on the agenda, it will cycle the
3069 visibility of its original location.
3071 ** Is there any way to set org-mode so that tags don't appear in the agenda view?
3073 See the =org-agenda-remove-tags= variable.
3075 ** I work late at night! How can I extend my current day past midnight?
3077 :CUSTOM_ID: org-extend-today-until
3080 If you work past midnight, you may not want your daily agenda view to
3081 switch to the next day at 12 a.m. (the default). To extend your day, simply
3082 set the value of org-extend-today-until to a positive number corresponding
3083 to the number of hours you work past midnight. For example, the following
3084 setting will cause the current day to extend until 6 a.m.
3086 : (setq org-extend-today-until 6)
3088 ** How can I let a task repeat until a certain date?
3090 Use =org-clone-subtree-with-time-shift= and read [[http://karl-voit.at/2017/01/15/org-clone-subtree-with-time-shift/][this blog post]] for
3093 * Appointments/Diary
3095 :CUSTOM_ID: Appointments/Diary
3097 ** Is it possible to include entries from org-mode files into my emacs diary?
3099 :CUSTOM_ID: include-entries-from-org-mode-files-into-emacs-diary
3104 Since the org-mode agenda is much more powerful and can contain the
3105 diary, you should think twice before deciding to do this. If you
3106 insist, however, integrating Org-mode information into the diary is
3107 possible. You need to turn on /fancy diary display/ by setting in
3110 : (add-hook 'diary-display-hook 'diary-fancy-display)
3112 Then include the following line into your ~/diary file, in
3113 order to get the entries from all files listed in the variable
3118 You may also select specific files with
3120 : &%%(org-diary) ~/path/to/some/org-file.org
3121 : &%%(org-diary) ~/path/to/another/org-file.org
3123 If you now launch the calendar and press ~d~ to display a
3124 diary, the headlines of entries containing a timestamp, date range,
3125 schedule, or deadline referring to the selected date will be listed.
3126 Just like Org-mode's agenda view, the diary for /today/ contains
3127 additional entries for overdue deadlines and scheduled items. See
3128 also the documentation of the =org-diary= function. Under XEmacs, it
3129 is not possible to jump back from the diary to the org, this works
3130 only in the agenda buffer.
3131 ** I want to add my Org scheduled/deadlined entries in my diary!
3133 :CUSTOM_ID: add-Org-scheduled/deadlined-entries-to-diary!
3136 Put this in your ~/.diary:
3138 : &%%(org-diary :scheduled :timestamp :deadline)
3140 ** How can I set up automatic reminders based on Org information?
3142 :CUSTOM_ID: automatic-reminders
3147 See [[https://orgmode.org/list/13222.1201471868@gamaville.dokosmarshall.org][this post]] by N. Dokos on the list. See also Russell Adams's hack in
3148 [[https://orgmode.org/worg/org-hacks.html#org-agenda-appt-zenity][org-hacks]].
3150 ** How can I make =appt= notice my Org appointments?
3152 :CUSTOM_ID: appt-notice-my-Org-appointments
3155 #+index: Appointment
3158 : M-x org-agenda-to-appt RET
3160 ** How can I create more complex appointments in my org-files?
3162 :CUSTOM_ID: diary-sexp-in-org-files
3165 #+index: Appointment
3167 Org-mode's active timestamps work very well for scheduling individual
3168 or recurring appointments, such as:
3171 ,* 8:00am Dentist appointment <2009-01-16 Fri>
3178 <2009-03-20 Fri>--<2009-04-01 Wed>
3184 ,* Weekly meeting with boss
3185 <2009-01-20 Tue 14:00 +1w>
3188 Sometimes, however, you need to set up more complicated recurring
3189 appointments. Org-mode has built-in support for many of [[http://www.gnu.org/software/emacs/manual/html_node/emacs/Sexp-Diary-Entries.html][the powerful sexp
3190 entries]] that work in [[http://www.gnu.org/software/emacs/manual/html_node/emacs/Diary.html#Diary][Emacs diary]].
3192 Let's say, for instance, that you teach a class that meets every Monday
3193 evening between February 16 and April 20, 2009. The way to enter this an
3197 ,** Class 7:00pm-9:00pm
3198 <%%(and (= 1 (calendar-day-of-week date)) (diary-block 2 16 2009 4 20 2009))>
3201 The expression above designates all Mondays that fall between February
3202 16 and April 20. How exactly does it work?
3204 - (and... :: Indicates that *both* of the conditions that follow have
3207 - (= 1 (calendar-day-of-week date)) :: Is the day of the week a
3210 - Note: the function calendar-day-of-week converts the date to the day of week
3211 expressed in numeric form, where 0 = Sunday, 1 = Monday, and so on.
3213 - (diary-block 2 16 2009 4 20 2009) :: Does the date fall between
3216 You can make a sexp as complex as you like. If you wanted to omit a week
3217 because of holidays, for instance, you could add another condition to the
3221 ,** Class 7:00pm-9:00pm
3222 <%%(unless (diary-block 3 9 2009 3 13 2009) (and (= 1 (calendar-day-of-week date)) (diary-block 2 16 2009 4 20 2009)))>
3225 The sexp above would omit Monday during the week of March 9, 2009. For
3226 another way to accomplish the same thing, see [[#org-class][this FAQ]].
3228 Another diary function commonly used for more complex scheduling is
3229 diary-float. For instance,
3233 <%%(diary-float t 3 3)>
3236 ... would appear on the third Wednesday of every month.
3238 For more ideas on how to create diary special expressions, see [[http://www.emacswiki.org/cgi-bin/wiki/DiaryMode][this
3239 page on the Emacs wiki]].
3241 ** How can I schedule a weekly class that lasts for a limited period of time?
3243 :CUSTOM_ID: org-class
3246 Org-mode offers a convenient diary sexp function for setting up a recurring
3247 appointment that lasts for a certain period of time, such as a class. It is
3248 called org-class and it can be entered as follows:
3251 ,** Class 7:00pm-9:00pm
3252 <%%(org-class 2009 2 16 2009 4 20 1 10)>
3255 The function above schedules an appointment for every Monday (1)
3256 between February 16 and April 20, 2009, except for ISO week 10 (March
3259 If you would prefer not to place the timestamp in the headline, you can use
3260 the following format:
3264 <%%(org-class 2009 2 16 2009 4 20 1 10)> 7:00pm-9:00pm Class
3267 In this case, the string following the sexp will be displayed in the
3270 The function org-class has the following format:
3272 : (org-class Y1 M1 D1 Y2 M2 D2 DAYNAME &rest SKIP-WEEKS)
3274 Y1/2, M1/2, and D1/2 indicate the beginning and ending dates. DAYNAME takes
3275 the form of a number indicating the day of the week (0 = Sunday, 1 =
3276 Monday, and so on...). In addition, one can add an optional argument
3277 SKIP-WEEKS to indicate weeks on the calendar that should be skipped. This
3278 argument should be expressed as an ISO week number. You can find the number
3279 by invoking emacs' built-in calendar (=M-x calendar=), navigating to the
3280 appropriate week, and typing =p c (calendar-iso-print-date)=. If one of
3281 the SKIP-WEEKS is the symbol =holidays=, then any holidays known to the
3282 calendar are also skipped.
3284 Here is an alternative method, shared by Paul Sexton on the org mailing
3287 Let's say you are taking night classes in Spanish. The class is every
3288 Wednesday evening at 7pm, starting on 18 August, and runs for 8
3289 weeks. Org-mode's timestamps do not support limited occurrences of
3290 recurrent items -- you have to schedule the item with infinite recurrences,
3291 then delete it when it finishes.
3293 To schedule the Spanish classes, put the following in your =.emacs=:
3295 #+begin_src emacs-lisp
3296 (defun diary-limited-cyclic (recurrences interval m d y)
3297 "For use in emacs diary. Cyclic item with limited number of recurrences.
3298 Occurs every INTERVAL days, starting on YYYY-MM-DD, for a total of
3299 RECURRENCES occasions."
3300 (let ((startdate (calendar-absolute-from-gregorian (list m d y)))
3301 (today (calendar-absolute-from-gregorian date)))
3302 (and (not (minusp (- today startdate)))
3303 (zerop (% (- today startdate) interval))
3304 (< (floor (- today startdate) interval) recurrences))))
3307 The item in the org file looks like this:
3310 ,** 19:00-21:00 Spanish lessons
3311 <%%(diary-limited-cyclic 8 7 8 18 2010)>
3314 ** How can I set an event to occur every day except Saturday and Sunday?
3318 <%%(memq (calendar-day-of-week date) '(1 2 3 4 5))>
3321 ** How do I schedule events relative to Easter Sunday?
3323 Easter's date moves around from year to year according to a complicated
3324 set of criteria which I do not claim to understand. However the
3325 following code will allow you to schedule recurring events relative to
3328 Note: the function da-easter is from [[http://github.com/soren/elisp/blob/master/da-kalender.el][da-kalender.el]].
3330 Put the following in your .emacs:
3332 #+begin_src emacs-lisp
3333 (defun da-easter (year)
3334 "Calculate the date for Easter Sunday in YEAR. Returns the date in the
3335 Gregorian calendar, ie (MM DD YY) format."
3336 (let* ((century (1+ (/ year 100)))
3337 (shifted-epact (% (+ 14 (* 11 (% year 19))
3338 (- (/ (* 3 century) 4))
3339 (/ (+ 5 (* 8 century)) 25)
3342 (adjusted-epact (if (or (= shifted-epact 0)
3343 (and (= shifted-epact 1)
3344 (< 10 (% year 19))))
3347 (paschal-moon (- (calendar-absolute-from-gregorian
3350 (calendar-dayname-on-or-before 0 (+ paschal-moon 7))))
3353 (defun da-easter-gregorian (year)
3354 (calendar-gregorian-from-absolute (da-easter year)))
3356 (defun calendar-days-from-easter ()
3357 "When used in a diary sexp, this function will calculate how many days
3358 are between the current date (DATE) and Easter Sunday."
3359 (- (calendar-absolute-from-gregorian date)
3360 (da-easter (calendar-extract-year date))))
3363 Now we can schedule the public holidays associated with Easter as
3364 recurring events. Good Friday is 2 days before "Easter", Easter Monday
3369 <%%(= -2 (calendar-days-from-easter))>
3372 <%%(= 0 (calendar-days-from-easter))>
3375 <%%(= 1 (calendar-days-from-easter))>
3378 [Source: Posted by Paul Sexton on Org-mode mailing list.]
3380 ** How to schedule public holiday that is "the nearest Monday to DATE"?
3382 In New Zealand each regional capital has an "Anniversary Day". The date
3383 of Auckland's anniversary day is "the nearest Monday to 29 January".
3385 Put this in your =.emacs=:
3387 #+begin_src emacs-lisp
3388 (defun calendar-nearest-to (target-dayname target-day target-month)
3389 "Recurring event that occurs in the nearest TARGET-DAYNAME to
3390 the date TARGET-DAY, TARGET-MONTH each year."
3392 (let* ((dayname (calendar-day-of-week date))
3393 (target-date (list target-month target-day (calendar-extract-year date)))
3394 (days-diff (abs (- (calendar-day-number date)
3395 (calendar-day-number target-date)))))
3396 (and (= dayname target-dayname)
3400 Now we can schedule Auckland Anniversary Day. The first argument, 1,
3401 means Monday (days of the week are numbered starting with Sunday=0).
3403 [Source: Originally posted by Paul Sexton on Org-mode mailing list.]
3405 ** How to schedule public holiday on "the 4th Monday in October"?
3409 This does not require any additions to =.emacs=:
3413 <%%(diary-float 10 1 4)>
3416 ** Why isn't the agenda showing all the times I put under a single entry?
3418 :CATEGORY: multiple-timestamps-same-entry
3421 Probably because you have not set the following variable:
3423 : org-agenda-skip-additional-timestamps-same-entry
3425 The default value of this variable is t, which means that entries with
3426 multiple timestamps, such as the following...
3429 ,* Work really, really hard
3430 <2010-11-20 Sat 10:00>
3431 <2010-11-20 Sat 14:00>
3434 ... will only appear in the agenda at the time specified by the first
3435 timestamp. If you set =org-agenda-skip-additional-timestamps-same-entry= to
3436 nil, the item will appear will appear at all the times you specify.
3438 ** Can I import iCal events/appts from Gnus?
3443 Yes. Vagn Johansen wrote [[http://ozymandias.dk/emacs/org-import-calendar.el][org-import-calendar.el]] which lets you do this.
3449 ** How do I ignore a headline?
3451 This is one of the most common FAQs on the Org mailing list. The
3452 following export filter will allow headlines tagged =ignore= to be
3453 ignored during export, while their contents and children headlines
3454 are retained and children headlines are promoted to the level of
3455 the original headline. Alternately, a more in depth discussion
3456 with a variety of alternate solutions is available in org-hacks
3457 [[file:org-hacks.org::#ignoreheadline][here]].
3459 #+begin_src emacs-lisp
3460 ;; During export headlines which have the "ignore" tag are removed
3461 ;; from the parse tree. Their contents are retained (leading to a
3462 ;; possibly invalid parse tree, which nevertheless appears to function
3463 ;; correctly with most export backends) all children headlines are
3464 ;; retained and are promoted to the level of the ignored parent
3467 ;; This makes it possible to add structure to the original Org-mode
3468 ;; document which does not effect the exported version, such as in the
3469 ;; following examples.
3471 ;; Wrapping an abstract in a headline
3473 ;; * Abstract :ignore:
3474 ;; #+LaTeX: \begin{abstract}
3475 ;; #+HTML: <div id="abstract">
3480 ;; #+LaTeX: \end{abstract}
3482 ;; Placing References under a headline (using ox-bibtex in contrib)
3484 ;; * References :ignore:
3485 ;; #+BIBLIOGRAPHY: dissertation plain
3487 ;; Inserting an appendix for LaTeX using the appendix package.
3489 ;; * Appendix :ignore:
3490 ;; #+LaTeX: \begin{appendices}
3494 ;; #+LaTeX: \end{appendices}
3496 (defun org-export-ignore-headlines (data backend info)
3497 "Remove headlines tagged \"ignore\" retaining contents and promoting children.
3498 Each headline tagged \"ignore\" will be removed retaining its
3499 contents and promoting any children headlines to the level of the
3501 (org-element-map data 'headline
3503 (when (member "ignore" (org-element-property :tags object))
3504 (let ((level-top (org-element-property :level object))
3507 ;; recursively promote all nested headlines
3508 (org-element-map el 'headline
3510 (when (equal 'headline (org-element-type el))
3512 (setq level-diff (- (org-element-property :level el)
3514 (org-element-put-property el
3515 :level (- (org-element-property :level el)
3517 ;; insert back into parse tree
3518 (org-element-insert-before el object))
3519 (org-element-contents object)))
3520 (org-element-extract-element object)))
3524 (add-hook 'org-export-filter-parse-tree-functions 'org-export-ignore-headlines)
3527 ** My old beamer presentations does not look the same with =ox-beamer.el=
3529 :CUSTOM_ID: beamer-backwards-incompatibility
3532 #+index: Export!Beamer
3534 The new beamer introduced a few backwards incompatible changes.
3535 Some of these are discussed [[file:exporters/beamer/ox-beamer.org::#backwards-compatibility][here]]. If you think the discussion can
3536 be improved, please share your thoughts on the mailing list; better
3537 yet, improve the entry on Worg!
3539 ** How can I export <my favourite element> as <my favourite environment> or how can I transform the export output using filters
3544 #+index: Export!Filters
3546 It is often useful to be able to make small tweaks to the export
3547 output by using filters.
3549 There have been a lot of requests like this on the mailing list
3550 lately. Often a user wants to export an image in different ways
3551 during LaTeX export; or export different image files for different
3552 backends. All these can be easily achieved by using export
3553 filters. You can look at [[https://orgmode.org/list/20130719102315.GB9369@kuru.dyndns-at-home.com][this example]] on the mailing list. For a
3554 more general discussion on the "new" export engine, including a
3555 description of filters and how they work, see Nicolas Goaziou's
3556 [[https://orgmode.org/list/876229nrxf.fsf@gmail.com][announcement]]: it is very much worth reading in its entirety (except
3557 for the section on users of the experimental version who are by now
3558 extinct - as is the experimental version.)
3560 ** Can I get TODO items exported to HTML as lists, rather than as headlines?
3562 :CUSTOM_ID: export-TODO-items-as-lists
3565 #+index: Export!HTML
3567 If you plan to use ASCII or HTML export, make sure things you want to
3568 be exported as item lists are level 4 at least, even if that does
3569 mean there is a level jump. For example:
3571 : * Todays top priorities
3572 : **** TODO write a letter to xyz
3573 : **** TODO Finish the paper
3574 : **** Pick up kids at the school
3576 Alternatively, if you need a specific value for the heading/item
3577 transition in a particular file, use the =#+OPTIONS= line to
3578 configure the H switch.
3580 : #+OPTIONS: H:2; ...
3582 ** Can I export only a single subtree?
3584 :CUSTOM_ID: export-single-subtree
3587 #+index: Export!Subtree
3589 If you want to export a subtree, mark the subtree as region and then
3590 export. Marking can be done with =C-c @ C-x C-x=, for example.
3592 Alternatively, you can select option =1= in the org export dispatcher
3593 (e.g.., =C-c C-e 1 h= to export the current subtree to html).
3595 By default, the title of the exported file will be set to the heading
3596 of the subtree. You can, however, [[#export-options-for-subtree][customize the title and other export
3599 ** How can I customize export options for a single subtree?
3601 :CUSTOM_ID: export-options-for-subtree
3604 #+index: Export!Options
3606 You can set unique export options for a [[#export-single-subtree][single subtree]] by using
3607 properties. Relevant properties include:
3612 - =EXPORT_FILE_NAME=
3613 - =EXPORT_OPTIONS= (corresponds to the =#+OPTIONS:= [[https://orgmode.org/manual/Export-settings.html#Export-settings][configuration line]])
3615 ** How can I tell my calendar web application about appointments in my agenda files?
3617 Here is what you need to do:
3619 1. a script that calls Emacs in batch mode and produce a .ics file
3620 2. a script that uploads this .ics file somewhere on the web
3621 3. tell your webapp to fetch this .ics file on the web
3623 Here is the script I use for the first step:
3625 #+begin_src shell-script-mode
3628 /usr/local/bin/emacs --batch --eval \
3629 "(progn (load-file \"~/install/git/org-mode/org.el\") \
3630 (load-file \"~/elisp/config/org-batch-config.el\") \
3631 (setq org-combined-agenda-icalendar-file \"~/org/cal/org.ics\")
3632 (setq org-agenda-files (quote (\"~/org/bzg.org\"))))" \
3633 -f org-export-icalendar-combine-agenda-files
3636 Depending on your configuration, you might change the load sequence.
3638 Here is the script I use for the second step:
3640 #+begin_src shell-script-mode
3642 /usr/bin/rsync -rtv ~/org/org.ics -e ssh me@my_server:/home/me/public_html/
3645 Note: if you want to cron this rsync script, you will need to let
3646 =my_server= to know about your SSH public key. Check [[http://troy.jdmz.net/rsync/index.html][this page]] as a
3649 Now you can cron the two scripts above and your webapp will always be
3650 up to date with your Org agendas.
3652 Also see [[https://orgmode.org/org.html#Exporting-Agenda-Views][Exporting agenda views]] from Org manual.
3654 ** How can I get Mac OSX 10.3 iCal to import my org-exported .ics files?
3656 :CUSTOM_ID: iCal-import-ics-files-old
3660 #+index: iCal!Mac OSX 10.3
3662 When using iCal under Apple MacOS X Tiger, you can create a new C-e c=,
3663 see the variables =org-icalendar-combined-name= and
3664 =org-combined-agenda-icalendar-file=). Then set Org-mode to overwrite
3665 the corresponding file /~/Library/Calendars/OrgMode.ics/. You may even
3666 use AppleScript to make iCal re-read the calendar files each time a new
3667 version of /OrgMode.ics/ is produced. Here is the setup needed for
3670 : (setq org-combined-agenda-icalendar-file
3671 : "~/Library/Calendars/OrgMode.ics")
3672 : (add-hook 'org-after-save-iCalendar-file-hook
3675 : "osascript -e 'tell application \"iCal\" to reload calendars'")))
3677 ** How can I get Mac OSX 10.4 or later iCal to import my Org-exported .ics files?
3679 :CUSTOM_ID: iCal-import-ics-files-new
3682 #+index: iCal!Mac OSX 10.4
3684 For Mac OS X 10.4, you need to write the ics file to
3685 =/Library/WebServer/Documents/= and then subscribe iCalendar to =http:
3686 //localhost/orgmode.ics=
3688 ** How can I remove timestamps and todo keywords from my exported file?
3690 :CUSTOM_ID: export-options-remove-timestamps
3693 #+index: Export!Timestamps
3694 #+index: Export!Todo keywords
3696 You can place an options line at the top of your org file:
3698 : #+OPTIONS: <:nil todo:nil
3700 There is a whole host of export options you can set with an in-buffer
3701 options or via global variables. See [[https://orgmode.org/manual/Export-settings.html#Export-settings][this section]] of the manual for a
3704 ** How can I preserve faces when I export an agenda from the command line?
3706 :CUSTOM_ID: preserving-faces-during-batch-export
3709 #+index: Export!Agenda
3710 #+index: Export!Faces
3712 Normally, when you export an org file or an agenda view from within
3713 emacs, htmlize will convert your face definitions to direct color css
3714 styles inlined into each =<span>= object, resulting in an HTML output
3715 that preserves the general look of your Org buffers and agenda views.
3717 Let's say you generate an export from the command line, such as the
3720 : emacs -batch -l ~/.emacs -eval '(org-batch-agenda "e")'
3724 : emacs -batch -l ~/.emacs -eval '(org-publish-all)'
3726 In such an instance, the exported HTML will contain only very basic
3727 color styles. The reason is that when Emacs is run in batch mode, it
3728 does not have a display and therefore only rudimentary face
3729 definitions. If you'd like to use more complex styles, you'll have to
3730 make sure that the export process only assigns classes instead of
3731 direct color values. This can be done by binding the variable
3732 =org-export-htmlize-output-style= to =css= for the duration of the
3733 export, for example with
3735 : emacs -batch -l ~/.emacs
3736 : -eval '(let ((org-export-htmlize-generate-css (quote css)))
3737 : (org-batch-agenda "e"))'
3739 Then you can use a style file to make these classes look any way you
3740 like. To generate face definitions for a CSS file based on any faces
3741 you are currently using in Emacs, you can use the following command:
3743 : M-x org-export-htmlize-generate-css RET
3745 This will generate a =<style>...</style>= section, the content of
3746 which you can add to your style file.
3748 ** How can I avoid dark color background when exporting agenda to ps format?
3750 :CUSTOM_ID: avoiding-dark-background-when-exporting-agenda
3755 Add this to your .emacs and evaluate it.
3757 #+BEGIN_SRC emacs-lisp
3758 (setq org-agenda-exporter-settings
3759 '((ps-print-color-p 'black-white)))
3762 ** How can I include e.g. an abstract in export to Latex and HTML?
3764 :CUSTOM_ID: include-abstract-in-export-to-latex-and-html
3767 #+index: Export!Abstract
3769 Org does not currently have special markup for abstracts, but for
3770 export purposes, you can extend the block-level structural and
3771 semantic markup in Org with the contributed package [[file:org-contrib/org-special-blocks.org][org-special-blocks]]
3772 (by Chris Gray). To turn it on, put this in your =.emacs=:
3774 : (require 'org-special-blocks)
3776 Now, you can mark up the abstract of your article like this:
3779 : Falling apples were observed and compared with pears. Newton's laws
3780 : were confirmed at the 95% confidence level.
3783 Exporting to Latex wraps this in a
3784 =\begin{abstract}....\end{abstract}= environment, which just works.
3786 HTML export wraps it in a ~<div class="abstract">...</div>~
3787 element. The HTML result won't look like anything special until you
3788 style it. Here is some sample CSS to get you started; put these in
3789 your document header:
3791 : #+STYLE: <style>.abstract {margin: 1em; padding: 1em; border: 1px solid black}
3792 : #+STYLE: .abstract:before {content: "Abstract: "; font-weight: bold}</style>
3794 Generally, =#+begin_foo= will work for any simple Latex =foo=
3795 environment not supported by existing Org markup.
3797 If you need to pass parameters, process the block content in some way,
3798 or support other exporters, you may want to consider whether you can
3799 customize it using Eric Schulte's [[file:org-contrib/org-exp-blocks.org][org-exp-blocks]] instead.
3801 ** How can I get colored source code when exporting to LaTeX?
3803 :CUSTOM_ID: fontified_source_code_w_latex
3806 #+index: Export!LaTeX
3808 As of Sun Aug 9 2009 the "current" version of Org-mode (see
3809 [[#keeping-current-with-Org-mode-development]]) supports exporting source
3810 code to LaTeX using the listings package.
3812 To turn on listing export add the following to your Org-mode
3814 #+begin_src emacs-lisp
3815 ;; requite org-latex so that the following variables are defined
3818 ;; tell org to use listings
3819 (setq org-latex-listings t)
3821 ;; you must include the listings package
3822 (add-to-list 'org-latex-packages-alist '("" "listings"))
3824 ;; if you want colored source code then you need to include the color package
3825 (add-to-list 'org-latex-packages-alist '("" "color"))
3828 The listings package will now be used to fontify source code in your
3829 LaTeX documents. By default listings will not color any of your
3830 source code. If you would like to set colors for keywords and
3831 comments in your latex documents you can do so using LaTeX directives
3834 \lstset{keywordstyle=\color{blue},
3835 commentstyle=\color{red},
3836 stringstyle=\color{green}
3840 of if you want to get even fancier with your colors you can try
3841 something like the following
3843 \definecolor{keywords}{RGB}{255,0,90}
3844 \definecolor{comments}{RGB}{60,179,113}
3845 \definecolor{fore}{RGB}{249,242,215}
3846 \definecolor{back}{RGB}{51,51,51}
3848 basicstyle=\color{fore},
3849 keywordstyle=\color{keywords},
3850 commentstyle=\color{comments},
3851 backgroundcolor=\color{back}
3855 For more complex listings use cases consult the [[ftp://ftp.tex.ac.uk/tex-archive/macros/latex/contrib/listings/listings.pdf][listings manual]].
3857 ** How can I export to Latex Beamer?
3862 #+index: Export!Beamer
3864 The latex [[http://latex-beamer.sourceforge.net/][Beamer Class]] is a useful class for generating slide shows.
3865 The following can be used to export Org-mode documents to LaTeX
3868 Add the following to your Emacs initialization file.
3869 #+begin_src emacs-lisp
3870 (unless (boundp 'org-latex-classes)
3871 (setq org-latex-classes nil))
3872 (add-to-list 'org-latex-classes
3874 "\\documentclass[11pt]{beamer}\n\\usepackage[utf8]{inputenc}\n\\usepackage[T1]{fontenc}\n\\usepackage{hyperref}\n\\usepackage{verbatim}\n"
3875 ("\\section{%s}" . "\\section*{%s}")
3876 ("\\begin{frame}\\frametitle{%s}" "\\end{frame}"
3877 "\\begin{frame}\\frametitle{%s}" "\\end{frame}")))
3881 : #+LaTeX_CLASS: beamer
3882 in the header of your Org-mode document it will automatically export
3883 to the Beamer document class on LaTeX export. With the above
3884 configuration top-level headers will be mapped to sections in the
3885 Beamer document, second-level headers will be mapped to frames, and
3886 lower level headlines will be mapped to itemize objects.
3888 This above is adapted from an [[https://orgmode.org/list/9854.1246500519@gamaville.dokosmarshall.org][email by Nick Dokos]], and an [[https://orgmode.org/list/935736B7-18C4-4730-B765-D9E8463E9C84@tsdye.com][email by
3889 Thomas Dye]]. For a much more complex Beamer setup see the [[https://orgmode.org/list/935736B7-18C4-4730-B765-D9E8463E9C84@tsdye.com][email by
3892 ** How can I use RefTeX in Org-mode files for LaTeX export and in Org-babel LaTeX code blocks?
3894 :CUSTOM_ID: using-reftex-in-org-mode
3899 #+index: Code blocks
3901 [[http://www.gnu.org/software/auctex/reftex.html][RefTeX]] is an indispensable tool for the author of LaTeX documents. It
3902 aids in creation of bibliographies, cross-references, indexes, and
3903 glossaries. RefTeX understands the structure of multi-file LaTeX
3904 documents and is able to collect from them information about the
3905 location(s) of external data stores used in creation of the final
3906 document. RefTeX was written by Carsten Dominik and is currently
3907 being maintained by the [[http://www.gnu.org/software/auctex/index.html][AucTeX]] project.
3909 *** Using RefTeX In Org-mode Files for LaTeX Export
3910 In Org-mode files for LaTeX export, the trick is to find a way to tell
3911 RefTeX the locations of external data stores. One way is to set the
3912 variable, =reftex-default-bibliography=. Add lines like these to
3915 #+begin_src emacs-lisp
3916 (setq reftex-default-bibliography
3918 ("default.bib" "other-default.bib")))
3921 In practice, this is a limited solution and the
3922 typical user will want to pass this information on a per-file basis.
3923 Two solutions to this problem were posted on a blog, [[http://www.mfasold.net/blog/2009/02/using-emacs-org-mode-to-draft-papers/][Mario's
3926 The first solution, proposed by Mario, enables the RefTeX citation
3927 function in Org-mode. Add these lines to .emacs:
3929 #+begin_src emacs-lisp
3930 (defun org-mode-reftex-setup ()
3931 (load-library "reftex")
3932 (and (buffer-file-name)
3933 (file-exists-p (buffer-file-name))
3935 (define-key org-mode-map (kbd "C-c )") 'reftex-citation))
3936 (add-hook 'org-mode-hook 'org-mode-reftex-setup)
3939 Then add the following lines anywhere in the Org-mode file (Org-mode
3940 will recognize them as LaTeX commands):
3943 \bibliographystyle{plain}
3944 \bibliography{BIB-NAME}
3947 With this setup, =C-c )= will invoke =reftex-citation= which will
3948 insert a reference in the usual way:
3953 This is a citation \cite{tierney90}.
3955 \bibliographystyle{plain}
3959 This Org-mode file will export the following LaTeX output:
3961 #+begin_src latex :exports code
3962 % Created 2010-03-22 Mon 14:34
3963 \documentclass[11pt,letter]{article}
3964 \usepackage[utf8]{inputenc}
3965 \usepackage[T1]{fontenc}
3966 \usepackage{hyperref}
3970 \date{2010-03-22 Mon}
3976 \setcounter{tocdepth}{3}
3980 \section{test reftex}
3984 This is a citation \cite{tierney90}.
3986 \bibliographystyle{plain}
3993 A second solution, to activate the RefTeX minor mode on a per-file
3994 basis, was posted by Kevin Brubeck Unhammer in response to this idea.
3995 Add the following lines to .emacs:
3997 #+begin_src emacs-lisp
3998 (add-hook ‘org-mode-hook
4000 (if (member “WRITE” org-todo-keywords-1)
4001 (org-mode-article-modes))))
4004 where =org-mode-article-modes= is defined as follows:
4006 #+begin_src emacs-lisp
4007 (defun org-mode-article-modes ()
4009 (bib-cite-minor-mode t)
4010 (and (buffer-file-name)
4011 (file-exists-p (buffer-file-name))
4012 (reftex-parse-all)))
4015 Add the =\bibliographystyle{}= and =\bibliography{}= lines to the
4016 Org-mode file as before and define a TODO keyword, =WRITE=, perhaps
4020 ,#+TODO: TODO(t) STARTED(s) WRITE | DONE(d) DEFERRED(f)
4023 With this setup, you insert a citation with =M-x reftex-citation RET=.
4025 *** Using RefTeX in Org-babel LaTeX Code Blocks
4027 In Org-babel LaTeX code blocks, the trick is to give RefTeX access to
4028 information in other Org-babel LaTeX code blocks. If you use an Emacs
4029 starter kit where configuration information is held in Org-mode files,
4030 then the second solution is preferable because you won't be asked for
4031 a master file when Emacs is started. For this reason, the second
4032 solution is modified for use with Org-babel latex code blocks. No
4033 key-binding is needed here because Org-babel code blocks are edited
4034 within the usual AucTeX environment.
4036 Add the following lines to .emacs (adapted from Kevin Brubeck Unhammer's [[http://www.mfasold.net/blog/2009/02/using-emacs-org-mode-to-draft-papers/][Reftex Setup]])
4037 #+begin_src emacs-lisp
4038 (defun org-mode-article-modes ()
4040 (and (buffer-file-name)
4041 (file-exists-p (buffer-file-name))
4042 (reftex-parse-all)))
4044 (add-hook 'org-mode-hook
4046 (if (member "REFTEX" org-todo-keywords-1)
4047 (org-mode-article-modes))))
4050 Then add a line like the following line to the top of your org-mode file:
4053 ,#+TODO: TODO(t) STARTED(s) | DONE(d) DEFERRED(f) REFTEX
4056 When you open an org-mode file with a line like this, RefTeX will
4057 prompt for the master .tex file, which will be parsed in the usual
4058 way. This means that the .tex file should already exist, perhaps by
4059 tangling the LaTeX preamble and postamble, before
4060 =org-mode-article-modes= is activated for the Org-mode file.
4062 ** How can I use XeLaTeX for LaTeX export instead of pdfLaTeX?
4064 :CUSTOM_ID: using-xelatex-for-pdf-export
4070 [[https://en.wikipedia.org/wiki/XeTeX][XeLaTeX]] is an alternative to pdfLaTeX for typesetting LaTeX
4071 documents. XeTeX can use any fonts installed in the operating system
4072 without configuring TeX font metrics, and can make direct use of advanced
4073 typographic features of OpenType and other font formats. By default,
4074 org-mode exports =org= files to =pdf= via pdfLaTeX.
4076 Here is one way to smoothly incorporate XeLaTeX into org-mode's export
4077 process. This solution takes advantage of [[http://www.phys.psu.edu/~collins/software/latexmk-jcc][latexmk]], a perl script that
4078 intelligently and automatically manages latex compilation. It is included
4079 with TeXLive, but at present the version included is not quite up-to-date
4080 enough for our needs. Version 4.20 and higher includes an option allowing
4081 you to specify which program to use when "pdflatex" is called. Install a
4082 current version of latexmk as per the instructions on the [[http://www.phys.psu.edu/~collins/software/latexmk-jcc][latexmk]] site. If
4083 necessary, disable the older version that comes with TeXLive. This is
4084 likely in =/usr/texbin/=, and you should rename or remove it. Then you can
4085 put the following in your =~/.emacs.d/= or equivalent:
4087 #+begin_src emacs-lisp
4089 (setq org-latex-listings t)
4091 ;; Originally taken from Bruno Tavernier: https://orgmode.org/list/87zkv0pqyi.fsf@mundaneum.com
4092 ;; but adapted to use latexmk 4.20 or higher.
4093 (defun my-auto-tex-cmd ()
4094 "When exporting from .org with latex, automatically run latex,
4095 pdflatex, or xelatex as appropriate, using latexmk."
4097 ;; default command: oldstyle latex via dvi
4098 (setq texcmd "latexmk -dvi -pdfps -quiet %f")
4100 (if (string-match "LATEX_CMD: pdflatex" (buffer-string))
4101 (setq texcmd "latexmk -pdf -quiet %f"))
4103 (if (string-match "LATEX_CMD: xelatex" (buffer-string))
4104 (setq texcmd "latexmk -pdflatex=xelatex -pdf -quiet %f"))
4105 ;; LaTeX compilation command
4106 (setq org-latex-to-pdf-process (list texcmd)))
4108 (add-hook 'org-export-latex-after-initial-vars-hook 'my-auto-tex-cmd)
4111 ;; Specify default packages to be included in every tex file, whether pdflatex or xelatex
4112 (setq org-latex-packages-alist
4114 ("" "longtable" nil)
4117 (defun my-auto-tex-parameters ()
4118 "Automatically select the tex packages to include."
4119 ;; default packages for ordinary latex or pdflatex export
4120 (setq org-latex-default-packages-alist
4121 '(("AUTO" "inputenc" t)
4131 ("" "hyperref" nil)))
4133 ;; Packages to include when xelatex is used
4134 (if (string-match "LATEX_CMD: xelatex" (buffer-string))
4135 (setq org-latex-default-packages-alist
4140 ("american" "babel" t)
4141 ("babel" "csquotes" t)
4143 ("xetex" "hyperref" nil)
4146 (if (string-match "LATEX_CMD: xelatex" (buffer-string))
4147 (setq org-latex-classes
4149 "\\documentclass[11pt,article,oneside]{memoir}"
4150 ("\\section{%s}" . "\\section*{%s}")
4151 ("\\subsection{%s}" . "\\subsection*{%s}")
4152 ("\\subsubsection{%s}" . "\\subsubsection*{%s}")
4153 ("\\paragraph{%s}" . "\\paragraph*{%s}")
4154 ("\\subparagraph{%s}" . "\\subparagraph*{%s}"))
4155 org-latex-classes))))
4157 (add-hook 'org-export-latex-after-initial-vars-hook 'my-auto-tex-parameters)
4160 The =my-auto-tex-cmd= function looks at your =.org= file and checks whether
4161 you've specified which latex to use. If there are no instructions, it just
4162 runs regular old latex. If it finds the string =LATEX_CMD: pdflatex= in
4163 your file, it runs pdflatex. If it finds =LATEX_CMD: xelatex=, it runs
4164 xelatex. Because control is handed off to latexmk, nothing else is needed:
4165 it takes care of figuring things out so that the references and citations
4168 The second half of the code above specifies the latex packages that will be
4169 included in the =.tex= file. The variable =org-latex-packages-alist=
4170 specifies a list of packages that are always included in the header of
4171 latex documents, regardless of how they are compiled. The variable
4172 =org-latex-default-packages-alist= adds additional packages
4173 depending on whether latex/pdflatex or xelatex is being used. You can
4174 change the content of these as needed.
4176 Finally, the =org-latex-classes= variable redefines elements of the
4177 =.tex= file's preamble for the xelatex case. These can also be customized
4180 By way of example, an =.org= file you want compiled with xelatex might
4181 contain the following header:
4184 : #+AUTHOR: Jane Doe
4186 : #+OPTIONS: toc:nil num:nil
4187 : #+LATEX_CMD: xelatex
4188 : #+LATEX_HEADER: \setsansfont[Mapping=tex-text]{Unit-Bold}
4189 : #+LATEX_HEADER: \setmonofont[Mapping=tex-text,Scale=MatchLowercase]{PragmataPro}
4190 : #+LATEX_HEADER: \setromanfont[Mapping=tex-text,Numbers=OldStyle]{Minion Pro}
4192 If you always want to have the same font setup in your xelatex documents,
4193 the =fontspec= commands setting the font choices can be put in the
4194 =org-latex-classes= setting instead.
4196 The upshot is that when you want to export an =.org= file using XeLaTeX,
4197 you can now simply make sure the line =LATEX_CMD: xelatex= is in your
4198 =.org= file, then do =C-c C-e d= as usual, and org-mode, with latexmk in
4199 the background, does the rest for you.
4201 ** Why is my exported PDF file almost unreadable?
4203 :CUSTOM_ID: unreadable-pdfs
4206 Some PDF viewers (earlier versions (< v6) of Acrobat Reader, Evince,
4207 possibly others) do not get along with Adobe Type3 fonts, producing almost
4208 unreadable screen output (printed output is OK). If you see this, first
4209 verify the fonts that your document uses: open it with Acrobat Reader or
4210 Evince, select "Properties" from the "File" menu and click on the "Fonts"
4211 tab; alternatively, you can use the pdffonts program (part of the
4212 xpdf-reader package) from the command line. If that is indeed the problem,
4213 then either use a different viewer or install Type1 versions of the
4214 problematic fonts. For more details, see the "PDF export" section of
4215 [[./org-dependencies.org][org-dependencies]].
4217 ** Can I add attributes to a link or an image in HTML export?
4219 :CUSTOM_ID: html-image-and-link-attributes
4222 #+index: Export!Link
4223 #+index: Export!Image
4224 #+index: Link!Attributes
4225 #+index: Image!Attributes
4227 Yes. Excerpt from [[https://orgmode.org/manual/Images-in-HTML-export.html#Images-in-HTML-export][Org's manual]]:
4229 If you need to add attributes to an inlined image, use a `#+ATTR_HTML'.
4230 In the example below we specify the `alt' and `title' attributes to
4231 support text viewers and accessibility, and align it to the right.
4233 : #+CAPTION: A black cat stalking a spider
4234 : #+ATTR_HTML: :alt cat/spider image :title Action! :align right
4237 and you could use `http' addresses just as well.
4239 ** How can I export an org file to rtf, odt (Open Office), or doc (Word)?
4241 :CUSTOM_ID: convert-to-open-office
4248 Orgmode exports natively to =OpenDocument= format using =org-odt= module.
4250 The key bindings for export are =C-c C-e o= and =C-c C-e O=.
4252 If you don't see =OpenDocumentText= as an option under =C-c C-e= you need
4253 to upgrade to =Org-mode 7.6= by one of the following means:
4255 1. Install org-7.6 using a distribution .zip or .tar.gz file, or
4256 through Git. Then do the following:
4257 1. Add =contrib/lisp= to the load-path in your =.emacs=
4258 #+begin_src emacs-lisp
4259 ;; modify org-root-dir as needed
4260 (add-to-list 'load-path "org-root-dir/contrib/lisp")
4262 2. Do =M-x customize-variable RET org-modules RET= and enable the
4265 2. Upgrade to (atleast) the =Emacs-24.1 pretest= version. Install
4266 =org-odt= package using =M-x list-packages=.
4270 - Use existing exporters
4272 Export to one of org-mode's supported export formats and then use an
4273 external tool or method to convert the exported file to doc or odt.
4275 With simple documents, these methods work well. However for complex
4276 documents containing footnotes, embedded images, math formuale etc
4277 the results may be less than satisfactory. (Note, the lists below
4278 are by no means comprehensive).
4279 1. html -> odt/doc/rtf
4280 - open html in Open Office and save as odt/doc ([[https://orgmode.org/list/87lj6btkim.wl%ucecesf@ucl.ac.uk][see this post by
4282 - [[http://www.artofsolving.com/opensource/pyodconverter][PyODConverter]]
4283 - [[http://johnmacfarlane.net/pandoc/][Pandoc]] (this works for LaTeX and docbook as well)
4284 - (Mac only) The [[http://developer.apple.com/library/mac/#DOCUMENTATION/Darwin/Reference/ManPages/man1/textutil.1.html][textutil]] utility bundled with OS X can convert
4286 2. LaTeX -> odt/doc/rtf
4287 - [[http://latex2rtf.sourceforge.net/][LaTeX2rtf]] (works well with index, footnotes, and references)
4288 - [[http://www.tug.org/tex4ht/][TeX4ht]] (works with more complex latex elements, though can be
4289 difficult to install)
4290 - run =mk4ht oolatex file.tex=
4292 See [[https://orgmode.org/list/AANLkTi=nbM9j=jO+wfBw9hTvnp_BXzQn51Pv7c0gKTRa@mail.gmail.com][this thread]] for further details.
4295 ** ODT export aborts on my Windows machine as I don't have zip installed. Where can I find a zip utility?
4299 You can either use [[https://en.wikipedia.org/wiki/Info-ZIP][Info-ZIP]] or zip package from Cygwin. Please customize
4300 =exec-path= to include the installation directory.
4302 ** I cannot open an exported =*.odt= file in LibreOffice because it is corrupt. What do I do?
4304 :CUSTOM_ID: debugging-org-odt
4309 Typically the corruption of =odt= file happens when the XML emitted by
4310 Org is not well-formed according to =OpenDocument schema=.
4312 If you encounter corruption issues please identify the root cause
4313 using one of the methods described below:
4315 - Use an Online validator
4316 - Pass the exported document through the [[http://tools.services.openoffice.org/odfvalidator/][ODF Validator]] and note down
4319 - Use Emacs' in-built validator
4320 1. Switch to =*.odt= buffer =(C-x b whatever.odt)=
4321 2. Open the =content.xml= file - =(Hit RET on content.xml)=
4322 3. Do a =C-u C-c C-n= - =(M-x rng-first-error)=
4323 4. Note the error message, the XML markup at the point of error and
4324 the surrounding context.
4326 Once you have identified the error
4327 1. Create a minimal org file that reproduces the error.
4328 2. Post a bug-report to =emacs-orgmode@gnu.org=.
4330 ** How can I specify ODT export styles?
4332 #+index: Export!odt style
4334 Check the variable =org-export-odt-styles-file=. Here is its docstring,
4335 as of Org version 7.8:
4337 : org-export-odt-styles-file is a variable defined in `org-odt.el'.
4341 : Default styles file for use with ODT export.
4342 : Valid values are one of:
4344 : 2. path to a styles.xml file
4345 : 3. path to a *.odt or a *.ott file
4346 : 4. list of the form (ODT-OR-OTT-FILE (FILE-MEMBER-1 FILE-MEMBER-2
4351 : Use "#+ODT_STYLES_FILE: ..." directive to set this variable on
4352 : a per-file basis. For example,
4354 : #+ODT_STYLES_FILE: "/path/to/styles.xml" or
4355 : #+ODT_STYLES_FILE: ("/path/to/file.ott" ("styles.xml" "image/hdr.png")).
4357 : You can customize this variable.
4359 ** Can I omit the title in the LaTeX export?
4361 Yes: simply use a blank #+TITLE in your Org file.
4363 ** How can I use arbitrary colors for words/sentences in HTML export?
4365 Add the following to your Emacs config,
4367 #+BEGIN_SRC emacs-lisp
4368 ;; -*- emacs-lisp -*-
4372 (message (concat "color "
4373 (progn (add-text-properties
4375 (list 'face `((t (:foreground ,path))))
4377 (lambda (path desc format)
4380 (format "<span style=\"color:%s;\">%s</span>" path desc))
4382 (format "{\\color{%s}%s}" path desc)))))
4385 and then you can use
4387 : [[color:red][red]]
4391 This question has been raised [[https://orgmode.org/list/44B0EAE8544C834188E8790873CDE1CC226BF8F8@ARCEXCHANGE.arc.local][on the mailing list]] by Jos'h Fuller and
4392 answered by Eric Schulte.
4395 ** How can I suppress the page number in the footer of an exported PDF?
4399 Use the following directive in your Org file:
4401 : #+LATEX: \thispagestyle{empty}
4407 Since =org= files are so central to your life, you probably want to back
4408 them up in a safe place.
4410 If the =org= file you want to back up are in a single directory, the
4411 preferred method is to us a =RCS= (Revision Control System) -- pick up your
4412 favorite ([[http://git-scm.com/][git]], [[http://bazaar.canonical.com/en/][bazaar]], [[http://mercurial.selenic.com/][mercurial]], [[http://subversion.apache.org/][subversion]], [[http://www.nongnu.org/cvs/][cvs]], etc.). Depending on the
4413 RCS you use and how you use it, you can have a /local/ backup or sync it on
4416 If you want to store all your =org= files from your =$HOME= to a single
4417 =~/org/backup/= folder, you can use this shell script (as [[https://orgmode.org/list/AANLkTimemfOeZFYajbpeW09OOJ87CVo-cTnarK-E=c3h@mail.gmail.com][suggested by
4421 mkdir -p ~/org/backup && \
4422 find $HOME -type f -name '*\.org' ! -path "$HOME/org/backup/*" \
4423 -exec cp -t ~/org/backup/ \{\} \;
4426 It will recursively search for =org= files in your =$HOME= directory
4427 (except those in =~/org/backup/=) and copy them to =~/org/backup/=.
4428 You can then use rsync to make sure =~/org/backup/= also lives on a
4429 remote and safe place.
4431 * Org-mode on mobile devices
4433 #+index: MobileDevices
4435 ** What mobile apps for org-mode are available?
4437 These are the most popular apps for keeping notes in org-mode format
4440 - MobileOrg for *iOS*, created by Richard Moreland. Check out [[https://mobileorg.github.io][the project's page]].
4441 - Orgzly for *Android*. See [[http://www.orgzly.com/][the project's page]]
4443 There is also an app called MobileOrg for *Android* which is now
4444 unmaintained and not fully compatible with recent versions of
4445 Android. See [[http://wiki.github.com/matburt/mobileorg-android/][the project page]].
4447 ** Can I use the same files on my mobile device as on my computer?
4449 Absolutely! Depending on the mobile app and your preferences, a number
4450 of options are available.
4452 *** Synchronizing using the MobileOrg protocol
4454 Org-mode in Emacs has a builtin protocol for synchronizing and merging
4455 changes from the mobile device. This protocol is supported by
4456 MobileOrg for iOS and by the (unmaintained) MobileOrg for Android, but
4457 *not* by Orgzly. Synchronization is initiated from within Emacs, which
4458 needs to fetch a file containing only the changes in a
4459 MobileOrg-specific file format. The file can be retrieved:
4461 - via [[http://www.dropbox.com/][Dropbox.com]] (easier to set up, free accounts available)
4462 - via [[https://syncthing.net/][Syncthing]] (open source and self hosted, potentially more data privacy)
4463 - via a [[https://en.wikipedia.org/wiki/WebDAV][WebDAV]] server of your choice (potentially more data privacy)
4465 **** How does synchronization via WebDAV work?
4467 :CUSTOM_ID: mobileorg_webdav
4470 You need to create a dedicated directory on the WebDAV server for the
4471 communication between Emacs and MobileOrg.
4473 #+begin_src ditaa :file images/orgmobile-tramp-webdav.png :cmdline -r
4474 +----------------------+ +----------------------+
4475 | desktop | | WebDAV server |
4476 +----------------------+ +----------------------+
4477 | emacs | | org-mobile-directory |
4478 | + org-mode | | containing: |
4480 | org-mobile-push -----------------> *.org |
4481 | org-mobile-pull <----------------- |
4483 +----------------------+ +-------|--------------+
4485 +----------------------+ |
4486 | mobile device | | WebDAV
4487 +----------------------+ |
4489 | MobileOrg <---------+
4491 +----------------------+
4495 [[file:images/orgmobile-tramp-webdav.png]]
4497 If you can mount that directory locally so that Emacs can directly
4498 write to it, just set the variable =org-mobile-directory= to point to
4499 that directory. Alternatively, by using the [[http://www.gnu.org/software/tramp/][/TRAMP/]] method,
4500 =org-mobile-directory= may point to a remote directory accessible
4501 through, for example, /ssh/ and /scp/:
4503 #+begin_src emacs-lisp
4504 (setq org-mobile-directory "/scpc:user@remote.host:org/webdav/")
4507 {{{BeginWarningBox}}} N.B. Since this configures /TRAMP/ to connect
4508 via /ssh/, you will need to use your /ssh/ password, not a WebDAV
4511 Also note that if you have configured ssh to use =ControlPersist=, due
4512 to [[https://lists.gnu.org/archive/html/tramp-devel/2012-03/msg00010.html][a bug with tramp and =ControlPersist=]] you may need to use =scpx=
4513 instead of =scp= as the /tramp/ transfer method.{{{EndWarningBox}}}
4515 **** Does Emacs have to use /TRAMP/ to access the remote directory?
4517 No, you can alternatively use a local directory for staging. Other
4518 means must then be used to keep this directory in sync with the WebDAV
4519 directory. In the following example, files are staged in =~/stage/=,
4520 and Org-mode hooks take care of moving files to and from the WebDAV
4521 directory using /scp/.
4523 #+begin_src emacs-lisp
4524 (setq org-mobile-directory "~/stage/")
4525 (add-hook 'org-mobile-post-push-hook
4526 (lambda () (shell-command "scp -r ~/stage/* user@wdhost:mobile/")))
4527 (add-hook 'org-mobile-pre-pull-hook
4528 (lambda () (shell-command "scp user@wdhost:mobile/mobileorg.org ~/stage/ ")))
4529 (add-hook 'org-mobile-post-pull-hook
4530 (lambda () (shell-command "scp ~/stage/mobileorg.org user@wdhost:mobile/")))
4533 Alternatively you could write a simple script to synchronize from
4534 =~/stage/= to the remote directory via /rsync/.
4536 *** Synchronizing with Syncthing or Dropbox directly
4538 Among Orgzly users it is popular to synchronize the org files
4539 themselves (rather than just the changesets) with [[https://syncthing.net/][Syncthing]] or
4540 [[http://www.dropbox.com/][Dropbox.com]]. This method provides no way of merging parallel edits, so
4541 you must ensure that a synchronization is performed when switching
4542 device, or you'll be in trouble. [[https://medium.com/@JosephKiran/replacing-cloud-based-to-do-apps-with-orgzly-and-syncthing-6a065419d61][This blog post]] provides some details
4543 for using Orgzly with Syncthing.
4545 *** Synchronizing with Git and a shell script
4547 An option which is attractive if you already prefer to have your org
4548 files version controlled by git is to initiate synchronization from a
4549 shell script on the computer, and handle merge conflicts with git
4550 merges. Edits made in parallel will be visible as parallel branches in
4551 the git log, and most conflicts should be handled by the
4552 auto-merger. [[https://pantarei.xyz/posts/sync-org-mode-with-mobile/][This blog post]] provides such a script with setup
4559 ** How to install MathJax on my server?
4561 :CUSTOM_ID: install_mathjax_on_server
4564 Org uses MathJax as its default HTML display engine for equations.
4566 Org relies on the version of MathJax available from orgmode.org, but you
4567 might want to use another version and install MathJax on your own server.
4569 1. Download a [[http://sourceforge.net/projects/mathjax/files/][MathJax archive]].
4571 2. Upload it somewhere on your server (say http://me.org/mathjax/)
4573 3. Set the correct path in =org-export-html-mathjax-options= (i.e. replace
4574 https://orgmode.org/mathjax/MathJax.js by
4575 http://me.org/mathjax/MathJax.js)
4577 You can also get [[http://www.mathjax.org/resources/docs/?installation.html][MathJax from git or svn]] -- in this case, be careful not to
4578 forget to unzip the fonts.zip archive in the mathjax directory.
4582 ** Can I create an Org link from a gmail email?
4586 Yes. See [[https://orgmode.org/list/4E9F8A54.5070007@gmail.com][this email]] from Torsten Wagner.
4588 Also check this comment by Tom:
4590 : Since any mail can be found under the All label by definition the
4591 : simplest solution is extracting the message id from the end of
4592 : the current url and then creating a new url pointing to All.
4593 : This URL should always work unless the mail is deleted:
4595 : https://mail.google.com/mail/?shva=1#all/<msgid>
4597 ** Problems with LaTeX macros with #+latex or #+begin_latex
4599 :CUSTOM_ID: Problems-with-LaTeX-macros-with-#+latex-or-#+begin_latex
4602 #+index: LaTeX!Macro
4604 Org's LaTeX exporter has a difficult job on its hands and even though it
4605 does a great job most of the time, there are times when it falls short. One
4606 situation that has arisen a few times in the past is when a macro
4607 definition or use includes an opening brace, but the corresponding closing
4608 brace is on a different line. That has caused LaTeX compilation problems or
4609 mysterious excisions of content - see for example the following two threads
4610 in the mailing list:
4612 - https://orgmode.org/list/87r5abi1tn.fsf@fastmail.fm
4614 - https://orgmode.org/list/BANLkTikRuyA7_sCC3pyVEHsJ0KXtP88_xw@mail.gmail.com
4616 In both cases, the exporter was getting confused by the opening brace which
4617 did not have a corresponding closing brace on the same line. Although the
4618 first of these cases is fixed in current Org, there might be more such
4619 cases or there might be a regression which causes the incorrect behavior
4620 again. While waiting for a fix, it's worth trying out the simple workaround
4621 of including a fake closing brace on the same line as the opening brace but
4622 *commenting it out* so that LaTeX never sees it. That is often enough to
4623 make the exporter behave properly. In other words, to take one of the
4624 examples above, instead of writing
4626 : #+latex: \custommacro {
4630 use the following idiom instead:
4632 : #+latex: \custommacro { % hide the closing brace in a LaTeX comment }
4636 I emphasize that this is a workaround, not a fix: if you do run into such
4637 a case and the workaround fixes it, at least you can continue working, but
4638 please submit a bug report so that it can be fixed properly.
4640 ** Inserting a Mairix type link when calling Orgmode capture in VM
4644 See the "rather crude solution" posted in [[http://robert-adesam.blogspot.com/2011/07/orgmode-capture-to-insert-mairix-link.html][this blog entry]] by Robert
4647 ** Can I prevent ispell from checking source blocks?
4651 #+BEGIN_SRC emacs-lisp
4652 (add-to-list 'ispell-skip-region-alist '("#\\+begin_src". "#\\+end_src"))
4655 ** Can I archive a subtree while keeping its hiearchy above?
4657 Yes, you can check this [[https://gist.github.com/edgimar/072d99d8650abe81a9fe7c8687c0c993][code]].
4659 * Google Summer of Code (GSoC)
4663 ** Does Org Mode participate in GNU's application for the GSoC 2012?
4665 :CUSTOM_ID: GSoC-2012
4670 Org Mode will contribute project ideas to GNU's application as
4671 mentoring organisation in Google's Summer of Code 2012 (see Google's
4672 [[http://www.google-melange.com/document/show/gsoc_program/google/gsoc2012/faqs][faq]]). You can have a look at the [[file:org-contrib/gsoc2012/index.org][GSoC 2012 page]] on Worg for more
4673 information about the project itself, and how to participate as
4676 * COMMENT Function to create =CUSTOM_ID=
4678 #+begin_src emacs-lisp
4679 (defun org-faq-make-target ()
4680 "Make hard target for current headline."
4682 (if (not (org-on-heading-p))
4683 (error "Not on a headline"))
4684 (let ((h (org-trim (org-get-heading 'no-tags))))
4685 (if (string-match "[ \t]*\\?\\'" h)
4686 (setq h (replace-match "" t t h)))
4687 (while (string-match "[ \t]+" h)
4688 (setq h (replace-match "-" t t h)))
4689 (org-entry-put nil "CUSTOM_ID" h)))