Mercurial > emacs
comparison man/org.texi @ 71386:0b2c58e8821c
(Publishing links): Document the
`:link-validation-function' property.
(Extensions and Hacking): New chapter, includes some sections
of
the "Miscellaneous" chapter.
author | Carsten Dominik <dominik@science.uva.nl> |
---|---|
date | Mon, 19 Jun 2006 06:54:43 +0000 |
parents | e050af4a9e72 |
children | 93e8ae57983b |
comparison
equal
deleted
inserted
replaced
71385:9ee77061d851 | 71386:0b2c58e8821c |
---|---|
1 \input texinfo | 1 \input texinfo |
2 @c %**start of header | 2 @c %**start of header |
3 @setfilename ../info/org | 3 @setfilename ../info/org |
4 @settitle Org Mode Manual | 4 @settitle Org Mode Manual |
5 | 5 |
6 @set VERSION 4.37 | 6 @set VERSION 4.38 |
7 @set DATE June 2006 | 7 @set DATE June 2006 |
8 | 8 |
9 @dircategory Emacs | 9 @dircategory Emacs |
10 @direntry | 10 @direntry |
11 * Org Mode: (org). outline-based notes management and organizer | 11 * Org Mode: (org). outline-based notes management and organizer |
84 * Tags:: Tagging headlines and matching sets of tags | 84 * Tags:: Tagging headlines and matching sets of tags |
85 * Agenda views:: Collecting information into views | 85 * Agenda views:: Collecting information into views |
86 * Exporting:: Sharing and publishing of notes | 86 * Exporting:: Sharing and publishing of notes |
87 * Publishing:: Create a web site of linked Org-mode files | 87 * Publishing:: Create a web site of linked Org-mode files |
88 * Miscellaneous:: All the rest which did not fit elsewhere | 88 * Miscellaneous:: All the rest which did not fit elsewhere |
89 * Extensions and Hacking:: | |
90 * History and Acknowledgments:: | |
89 * Index:: The fast road to specific information | 91 * Index:: The fast road to specific information |
90 * Key Index:: Key bindings and where they are described | 92 * Key Index:: Key bindings and where they are described |
91 | 93 |
92 @detailmenu | 94 @detailmenu |
93 --- The Detailed Node Listing --- | 95 --- The Detailed Node Listing --- |
160 * Creating timestamps:: Commands which insert timestamps | 162 * Creating timestamps:: Commands which insert timestamps |
161 * Progress logging:: Documenting when what work was done. | 163 * Progress logging:: Documenting when what work was done. |
162 | 164 |
163 Progress Logging | 165 Progress Logging |
164 | 166 |
165 * Closing items:: When was this entry makred DONE? | 167 * Closing items:: When was this entry marked DONE? |
166 * Clocking work time:: When exactly did you work on this item? | 168 * Clocking work time:: When exactly did you work on this item? |
167 | 169 |
168 Tags | 170 Tags |
169 | 171 |
170 * Tag inheritance:: Tags use the tree structure of the outline | 172 * Tag inheritance:: Tags use the tree structure of the outline |
229 * Customization:: Adapting Org-mode to your taste | 231 * Customization:: Adapting Org-mode to your taste |
230 * Summary of in-buffer settings:: Using special lines to set options | 232 * Summary of in-buffer settings:: Using special lines to set options |
231 * The very busy C-c C-c key:: When in doubt, press C-c C-c | 233 * The very busy C-c C-c key:: When in doubt, press C-c C-c |
232 * Clean view:: Getting rid of leading stars in the outline | 234 * Clean view:: Getting rid of leading stars in the outline |
233 * TTY keys:: Using Org-mode on a tty | 235 * TTY keys:: Using Org-mode on a tty |
234 * FAQ:: Frequently asked questions | |
235 * Interaction:: Other Emacs packages | 236 * Interaction:: Other Emacs packages |
236 * Bugs:: Things which do not work perfectly | 237 * Bugs:: Things which do not work perfectly |
237 * Acknowledgments:: These people provided feedback and more | |
238 | 238 |
239 Interaction with other packages | 239 Interaction with other packages |
240 | 240 |
241 * Extensions:: Third-party extensions for Org-mode | |
242 * Cooperation:: Packages Org-mode cooperates with | 241 * Cooperation:: Packages Org-mode cooperates with |
243 * Conflicts:: Packages that lead to conflicts | 242 * Conflicts:: Packages that lead to conflicts |
243 | |
244 Extensions and Hacking | |
245 | |
246 * Extensions:: | |
247 * Dynamic blocks:: | |
244 | 248 |
245 @end detailmenu | 249 @end detailmenu |
246 @end menu | 250 @end menu |
247 | 251 |
248 @node Introduction, Document structure, Top, Top | 252 @node Introduction, Document structure, Top, Top |
294 @end example | 298 @end example |
295 | 299 |
296 The Org-mode table editor can be integrated into any major mode by | 300 The Org-mode table editor can be integrated into any major mode by |
297 activating the minor Orgtbl-mode. | 301 activating the minor Orgtbl-mode. |
298 | 302 |
303 @cindex FAQ | |
299 There is a website for Org-mode which provides links to the newest | 304 There is a website for Org-mode which provides links to the newest |
300 version of Org-mode, as well as additional information, screen shots | 305 version of Org-mode, as well as additional information, frequently asked |
301 and example files. This page is located at | 306 questions (FAQ), links to tutorials etc. This page is located at |
302 @uref{http://www.astro.uva.nl/~dominik/Tools/org/}. | 307 @uref{http://www.astro.uva.nl/~dominik/Tools/org/}. |
303 | 308 |
304 @page | 309 @page |
305 | 310 |
306 @node Installation and activation, Feedback, Summary, Introduction | 311 @node Installation and activation, Feedback, Summary, Introduction |
338 | 343 |
339 @lisp | 344 @lisp |
340 ;; This line only if org-mode is not part of the X/Emacs distribution. | 345 ;; This line only if org-mode is not part of the X/Emacs distribution. |
341 (require 'org-install) | 346 (require 'org-install) |
342 @end lisp | 347 @end lisp |
348 | |
349 If you use Org-mode with XEmacs, you also need to install the file | |
350 @file{noutline.el} from the @file{xemacs} subdirectory of the Org-mode | |
351 distribution. | |
343 | 352 |
344 @cindex org-mode, turning on | 353 @cindex org-mode, turning on |
345 With this setup, all files with extension @samp{.org} will be put into | 354 With this setup, all files with extension @samp{.org} will be put into |
346 Org-mode. As an alternative, make the first line of a file look like | 355 Org-mode. As an alternative, make the first line of a file look like |
347 this: | 356 this: |
619 When a project represented by a (sub)tree is finished, you may want | 628 When a project represented by a (sub)tree is finished, you may want |
620 to move the tree to an archive place, either in the same file under a | 629 to move the tree to an archive place, either in the same file under a |
621 special top-level heading, or even to a different file. | 630 special top-level heading, or even to a different file. |
622 @table @kbd | 631 @table @kbd |
623 @kindex C-c $ | 632 @kindex C-c $ |
624 @item @kbd{C-c $} | 633 @item C-c $ |
625 Archive the subtree starting at the cursor position to the location | 634 Archive the subtree starting at the cursor position to the location |
626 given by @code{org-archive-location}. | 635 given by @code{org-archive-location}. |
636 @kindex C-u C-c $ | |
637 @item C-u C-c $ | |
638 When @kbd{C-c $} is called with @kbd{C-u} prefix argument, check for | |
639 (sub)trees without any open TODO items and offer to archive them. When | |
640 the cursor is on a headline when this command is called, inly check the | |
641 direct children of this headline. When the cursor is @emph{not} on a | |
642 headline, check all level 1 trees. | |
627 @end table | 643 @end table |
628 | 644 |
629 @cindex archive locations | 645 @cindex archive locations |
630 The default archive is a file in the same directory as the current | 646 The default archive is a file in the same directory as the current |
631 file, with the name derived by appending @file{_archive} to the | 647 file, with the name derived by appending @file{_archive} to the |
1672 @cindex inserting links | 1688 @cindex inserting links |
1673 @item C-c C-l | 1689 @item C-c C-l |
1674 Insert a link. This prompts for a link to be inserted into the buffer. | 1690 Insert a link. This prompts for a link to be inserted into the buffer. |
1675 You can just type a link, using text for an internal link, or one of the | 1691 You can just type a link, using text for an internal link, or one of the |
1676 link type prefixes mentioned in the examples above. Through completion, | 1692 link type prefixes mentioned in the examples above. Through completion, |
1677 all links stored during the current session can be accessed. The link | 1693 all links stored during the current session can be |
1694 accessed@footnote{After insertion of a stored link, the link will be | |
1695 removed from the list of stored links. To keep it in the list later | |
1696 use, use a triple @kbd{C-u} prefix to @kbd{C-c C-l}, or configure the | |
1697 option @code{org-keep-stored-link-after-insertion}.}. The link | |
1678 will be inserted into the buffer, along with a descriptive text. Note | 1698 will be inserted into the buffer, along with a descriptive text. Note |
1679 that you don't have to use this command to insert a link. Links in | 1699 that you don't have to use this command to insert a link. Links in |
1680 Org-mode are plain text, and you can type or paste them straight into | 1700 Org-mode are plain text, and you can type or paste them straight into |
1681 the buffer. By using this command, the links are automatically enclosed | 1701 the buffer. By using this command, the links are automatically enclosed |
1682 in double brackets, and you will be asked for the optional descriptive | 1702 in double brackets, and you will be asked for the optional descriptive |
2225 brackets instead of angular brackets. | 2245 brackets instead of angular brackets. |
2226 | 2246 |
2227 @item Time range with CLOCK keyword | 2247 @item Time range with CLOCK keyword |
2228 @cindex CLOCK keyword | 2248 @cindex CLOCK keyword |
2229 When using the clock to time the work that is being done on specific | 2249 When using the clock to time the work that is being done on specific |
2230 items, time ranges preceeded by the CLOCK keyword are inserted | 2250 items, time ranges preceded by the CLOCK keyword are inserted |
2231 automatically into the file. The time stamps are enclosed in square | 2251 automatically into the file. The time stamps are enclosed in square |
2232 brackets instead of angular brackets. @xref{Clocking work time}. | 2252 brackets instead of angular brackets. @xref{Clocking work time}. |
2233 @c FIXME: Reference needed | |
2234 @end table | 2253 @end table |
2235 | 2254 |
2236 @node Creating timestamps, Progress logging, Time stamps, Timestamps | 2255 @node Creating timestamps, Progress logging, Time stamps, Timestamps |
2237 @section Creating timestamps | 2256 @section Creating timestamps |
2238 @cindex creating timestamps | 2257 @cindex creating timestamps |
2374 as DONE. You can also measure precisely the time you spent on specific | 2393 as DONE. You can also measure precisely the time you spent on specific |
2375 items in a project by starting and stopping a clock when you start and | 2394 items in a project by starting and stopping a clock when you start and |
2376 stop working on an aspect of a project. | 2395 stop working on an aspect of a project. |
2377 | 2396 |
2378 @menu | 2397 @menu |
2379 * Closing items:: When was this entry makred DONE? | 2398 * Closing items:: When was this entry marked DONE? |
2380 * Clocking work time:: When exactly did you work on this item? | 2399 * Clocking work time:: When exactly did you work on this item? |
2381 @end menu | 2400 @end menu |
2382 | 2401 |
2383 @node Closing items, Clocking work time, Progress logging, Progress logging | 2402 @node Closing items, Clocking work time, Progress logging, Progress logging |
2384 @subsection Closing items | 2403 @subsection Closing items |
2403 @node Clocking work time, , Closing items, Progress logging | 2422 @node Clocking work time, , Closing items, Progress logging |
2404 @subsection Clocking work time | 2423 @subsection Clocking work time |
2405 | 2424 |
2406 Org-mode allows you to clock the time you spent on specific tasks in a | 2425 Org-mode allows you to clock the time you spent on specific tasks in a |
2407 project. When you start working on an item, you can start the clock. | 2426 project. When you start working on an item, you can start the clock. |
2408 When you stop working on that tast, or when you makr the task done, the | 2427 When you stop working on that task, or when you mark the task done, the |
2409 clock is stoppend and the corresponding time interval is recorded. It | 2428 clock is stopped and the corresponding time interval is recorded. It |
2410 also computes the total time spent on each subtree of a project. | 2429 also computes the total time spent on each subtree of a project. |
2411 | 2430 |
2412 @table @kbd | 2431 @table @kbd |
2413 @kindex C-c C-x C-i | 2432 @kindex C-c C-x C-i |
2414 @item C-c C-x C-i | 2433 @item C-c C-x C-i |
2433 Display time summaries for each subtree in the current buffer. This | 2452 Display time summaries for each subtree in the current buffer. This |
2434 puts overlays at the end of each headline, showing the total time | 2453 puts overlays at the end of each headline, showing the total time |
2435 recorded under that heading, including the time of any subheadings. You | 2454 recorded under that heading, including the time of any subheadings. You |
2436 can use visibility cycling to study the tree, but the overlays disappear | 2455 can use visibility cycling to study the tree, but the overlays disappear |
2437 automatically when the buffer is changed. | 2456 automatically when the buffer is changed. |
2457 @kindex C-c C-x C-r | |
2458 @item C-c C-x C-r | |
2459 Insert a dynamic block containing a clock report as an org-mode table | |
2460 into the current file. | |
2461 @example | |
2462 #+BEGIN: clocktable :maxlevel 2 :emphasize nil | |
2463 | |
2464 #+END: clocktable | |
2465 @end example | |
2466 @noindent | |
2467 If such a block already exists, its content is replaced by the new | |
2468 table. The @samp{BEGIN} line can specify options: | |
2469 @example | |
2470 :maxlevels @r{Maximum level depth to which times are listed in the table.} | |
2471 :emphasize @r{When @code{t}, emphasize level one and level two items} | |
2472 @end example | |
2438 @end table | 2473 @end table |
2439 | 2474 |
2440 The @kbd{l} key may be used in the timeline (@pxref{Timeline}) and in | 2475 The @kbd{l} key may be used in the timeline (@pxref{Timeline}) and in |
2441 the agenda (@pxref{Weekly/Daily agenda}) to show which tasks have been | 2476 the agenda (@pxref{Weekly/Daily agenda}) to show which tasks have been |
2442 worked on or closed during a day. | 2477 worked on or closed during a day. |
3762 | 3797 |
3763 You may also link to related files, such as images. Provided you are | 3798 You may also link to related files, such as images. Provided you are |
3764 careful with relative pathnames, and provided you have also configured | 3799 careful with relative pathnames, and provided you have also configured |
3765 org-publish to upload the related files, these links will work | 3800 org-publish to upload the related files, these links will work |
3766 too. @ref{Complex example} for an example of this usage. | 3801 too. @ref{Complex example} for an example of this usage. |
3802 | |
3803 Sometime an Org-mode file to be published may contain links that are | |
3804 only valid in your production environment, but not in the publishing | |
3805 location. In this case, use the property | |
3806 | |
3807 @multitable @columnfractions 0.4 0.6 | |
3808 @item @code{:link-validation-function} | |
3809 @tab Function to validate links | |
3810 @end multitable | |
3811 | |
3812 @noindent | |
3813 to define a function for checking link validity. This function must | |
3814 accept two arguments, the file name and a directory relative to which | |
3815 the file name is interpreted in the production environment. If this | |
3816 function returns @code{nil}, then the HTML generator will only insert a | |
3817 description into the HTML file, but no link. One option for this | |
3818 function is @code{org-publish-validate-link} which checks if the given | |
3819 file is part of any project in @code{org-publish-project-alist}. | |
3767 | 3820 |
3768 @node Project page index, , Publishing links, Configuration | 3821 @node Project page index, , Publishing links, Configuration |
3769 @subsection Project page index | 3822 @subsection Project page index |
3770 | 3823 |
3771 The following properties may be used to control publishing of an | 3824 The following properties may be used to control publishing of an |
3889 | 3942 |
3890 Org uses timestamps to track when a file has changed. The above | 3943 Org uses timestamps to track when a file has changed. The above |
3891 functions normally only publish changed files. You can override this and | 3944 functions normally only publish changed files. You can override this and |
3892 force publishing of all files by giving a prefix argument. | 3945 force publishing of all files by giving a prefix argument. |
3893 | 3946 |
3894 @node Miscellaneous, Index, Publishing, Top | 3947 @node Miscellaneous, Extensions and Hacking, Publishing, Top |
3895 @chapter Miscellaneous | 3948 @chapter Miscellaneous |
3896 | 3949 |
3897 @menu | 3950 @menu |
3898 * Completion:: M-TAB knows what you need | 3951 * Completion:: M-TAB knows what you need |
3899 * Customization:: Adapting Org-mode to your taste | 3952 * Customization:: Adapting Org-mode to your taste |
3900 * Summary of in-buffer settings:: Using special lines to set options | 3953 * Summary of in-buffer settings:: Using special lines to set options |
3901 * The very busy C-c C-c key:: When in doubt, press C-c C-c | 3954 * The very busy C-c C-c key:: When in doubt, press C-c C-c |
3902 * Clean view:: Getting rid of leading stars in the outline | 3955 * Clean view:: Getting rid of leading stars in the outline |
3903 * TTY keys:: Using Org-mode on a tty | 3956 * TTY keys:: Using Org-mode on a tty |
3904 * FAQ:: Frequently asked questions | |
3905 * Interaction:: Other Emacs packages | 3957 * Interaction:: Other Emacs packages |
3906 * Bugs:: Things which do not work perfectly | 3958 * Bugs:: Things which do not work perfectly |
3907 * Acknowledgments:: These people provided feedback and more | |
3908 @end menu | 3959 @end menu |
3909 | 3960 |
3910 @node Completion, Customization, Miscellaneous, Miscellaneous | 3961 @node Completion, Customization, Miscellaneous, Miscellaneous |
3911 @section Completion | 3962 @section Completion |
3912 @cindex completion, of @TeX{} symbols | 3963 @cindex completion, of @TeX{} symbols |
4041 | 4092 |
4042 The key @kbd{C-c C-c} has many purposes in org-mode, which are all | 4093 The key @kbd{C-c C-c} has many purposes in org-mode, which are all |
4043 mentioned scattered throughout this manual. One specific function of | 4094 mentioned scattered throughout this manual. One specific function of |
4044 this key is to add @emph{tags} to a headline (@pxref{Tags}). In many | 4095 this key is to add @emph{tags} to a headline (@pxref{Tags}). In many |
4045 other circumstances it means something like @emph{Hey Org-mode, look | 4096 other circumstances it means something like @emph{Hey Org-mode, look |
4046 here and update according to what you see here}. Here is a summary of what | 4097 here and update according to what you see here}. Here is a summary of |
4047 this means in different contexts. | 4098 what this means in different contexts. |
4048 | 4099 |
4049 @itemize @minus | 4100 @itemize @minus |
4050 @c @item | 4101 @item |
4051 @c If the cursor is in a headline, prompt for tags and insert them | 4102 If there are highlichts in the buffer from the creation of a sparse |
4052 @c into the current line, aligned to `org-tags-column'. When called | 4103 tree, or from clock display, remove these highlights. |
4053 @c with prefix arg, realign all tags in the current buffer. | |
4054 @item | 4104 @item |
4055 If the cursor is in one of the special @code{#+KEYWORD} lines, this | 4105 If the cursor is in one of the special @code{#+KEYWORD} lines, this |
4056 triggers scanning the buffer for these lines and updating the | 4106 triggers scanning the buffer for these lines and updating the |
4057 information. | 4107 information. |
4058 @item | 4108 @item |
4178 You can convert an Org-mode file from single-star-per-level to the | 4228 You can convert an Org-mode file from single-star-per-level to the |
4179 double-star-per-level convention with @kbd{M-x org-convert-to-odd-levels | 4229 double-star-per-level convention with @kbd{M-x org-convert-to-odd-levels |
4180 RET} in that file. The reverse operation is @kbd{M-x | 4230 RET} in that file. The reverse operation is @kbd{M-x |
4181 org-convert-to-oddeven-levels}. | 4231 org-convert-to-oddeven-levels}. |
4182 | 4232 |
4183 @node TTY keys, FAQ, Clean view, Miscellaneous | 4233 @node TTY keys, Interaction, Clean view, Miscellaneous |
4184 @section Using org-mode on a tty | 4234 @section Using org-mode on a tty |
4185 @cindex tty keybindings | 4235 @cindex tty keybindings |
4186 | 4236 |
4187 Org-mode uses a number of keys that are not accessible on a tty. This | 4237 Org-mode uses a number of keys that are not accessible on a tty. This |
4188 applies to most special keys like cursor keys, @key{TAB} and | 4238 applies to most special keys like cursor keys, @key{TAB} and |
4215 @item @kbd{S-@key{right}} @tab @kbd{C-c C-x @key{right}} @tab | 4265 @item @kbd{S-@key{right}} @tab @kbd{C-c C-x @key{right}} @tab |
4216 @item @kbd{S-@key{up}} @tab @kbd{C-c C-x @key{up}} @tab | 4266 @item @kbd{S-@key{up}} @tab @kbd{C-c C-x @key{up}} @tab |
4217 @item @kbd{S-@key{down}} @tab @kbd{C-c C-x @key{down}} @tab | 4267 @item @kbd{S-@key{down}} @tab @kbd{C-c C-x @key{down}} @tab |
4218 @end multitable | 4268 @end multitable |
4219 | 4269 |
4220 @node FAQ, Interaction, TTY keys, Miscellaneous | 4270 @node Interaction, Bugs, TTY keys, Miscellaneous |
4221 @section Frequently asked questions | |
4222 @cindex FAQ | |
4223 | |
4224 @enumerate | |
4225 @cindex @code{keymapp nil} error | |
4226 @item @b{When I try to use Org-mode, I always get | |
4227 @code{(wrong-type-argument keymapp nil)}}.@* | |
4228 @cindex allout.el, conflict with | |
4229 This is a conflict with an outdated version of the @file{allout.el}. | |
4230 See @ref{Conflicts}. | |
4231 | |
4232 @item @b{Org-mode seems to be a useful default mode for the various | |
4233 @file{README} files I have scattered through my directories. How do I | |
4234 turn it on for all @file{README} files?} | |
4235 | |
4236 @lisp | |
4237 (add-to-list 'auto-mode-alist '("README$" . org-mode)) | |
4238 @end lisp | |
4239 | |
4240 @item @b{I would like to use editing features of org-mode in other | |
4241 modes, is this possible?}@* | |
4242 @c | |
4243 Not really. For tables there is @code{orgtbl-mode} which implements the | |
4244 table editor as a minor mode. For other features you need to switch to | |
4245 Org-mode temporarily, or prepare text in a different buffer. | |
4246 | |
4247 @item @b{Can I get the visibility-cycling features in outline-mode and | |
4248 outline-minor-mode?}@* | |
4249 @c | |
4250 Yes, these functions are written in a way that they are independent of | |
4251 the outline setup. The following setup provides standard Org-mode | |
4252 functionality in outline-mode on @key{TAB} and @kbd{S-@key{TAB}}. For | |
4253 outline-minor-mode, we use @kbd{C-@key{TAB}} instead of @key{TAB}, | |
4254 because @key{TAB} usually has mode-specific tasks. | |
4255 @lisp | |
4256 (add-hook 'outline-minor-mode-hook | |
4257 (lambda () | |
4258 (define-key outline-minor-mode-map [(control tab)] 'org-cycle) | |
4259 (define-key outline-minor-mode-map [(shift tab)] 'org-global-cycle))) | |
4260 (add-hook 'outline-mode-hook | |
4261 (lambda () | |
4262 (define-key outline-mode-map [(tab)] 'org-cycle) | |
4263 (define-key outline-mode-map [(shift tab)] 'org-global-cycle))) | |
4264 @end lisp | |
4265 | |
4266 Or check out @file{outline-magic.el}, which does this and also provides | |
4267 promotion and demotion functionality. @file{outline-magic.el} is | |
4268 available at @url{http://www.astro.uva.nl/~dominik/Tools/OutlineMagic}. | |
4269 | |
4270 @item @b{Some of my links stopped working after I upgraded to a version | |
4271 4.20 or later. Why is this, and how can I fix it?}@* | |
4272 @c | |
4273 These must be links in plain text, containing white space, such as | |
4274 @samp{bbdb:Richard Stallman}. You need to protect these links by | |
4275 putting double brackets around them, like @samp{[[bbdb:Richard | |
4276 Stallman]]}. | |
4277 | |
4278 @item @b{I see that Org-mode now creates links using the double bracket | |
4279 convention that hides the link part and the brackets, only showing the | |
4280 description part. How can I convert my old links to this new format?}@* | |
4281 @c | |
4282 Execute once in each Org-mode file: @kbd{M-x org-upgrade-old-links}. | |
4283 This replaces angular brackets with the new link format. | |
4284 | |
4285 @item @b{I don't care if you find the new bracket links great, I am | |
4286 attached to the old style using angular brackets and no hiding of the | |
4287 link text. Please give them back to me, don't tell me it is not | |
4288 possible!}@* | |
4289 @c | |
4290 Would I let you down like that? If you must, you can do this | |
4291 | |
4292 @lisp | |
4293 (setq org-link-style 'plain | |
4294 org-link-format "<%s>") | |
4295 @end lisp | |
4296 | |
4297 @item @b{When I am executing shell/elisp links I always get a | |
4298 confirmation prompt and need to type @kbd{yes @key{RET}}, that's 4 key | |
4299 presses! Can I get rid of this?}@* | |
4300 @c | |
4301 @cindex shell links, confirmation | |
4302 @cindex dangerous commands | |
4303 The confirmation is there to protect you from unwantingly execute | |
4304 potentially dangerous commands. For example, imagine a link | |
4305 @samp{[[shell:rm -rf ~/*][Google Search]]}. In an Org-mode buffer, this | |
4306 command would look like @samp{Google Search}, but really it would remove | |
4307 your home directory. If you wish, you can make it easier to respond to | |
4308 the query by setting @code{org-confirm-shell-link-function} and/or | |
4309 @code{org-confirm-elisp-link-function} to @code{y-or-n-p}. Then a | |
4310 single @kbd{y} keypress will be enough to confirm those links. It is | |
4311 also possible to turn off this check entirely, but I do not recommend to | |
4312 do this. Be warned. | |
4313 | |
4314 @item @b{All these stars are driving me mad, I just find the Emacs | |
4315 outlines unreadable. Can't you just put white space and a single star as a | |
4316 starter for headlines?}@* | |
4317 @c | |
4318 See @ref{Clean view}. | |
4319 | |
4320 @item @b{I would like to have two windows on the same Org-mode | |
4321 file, but with different outline visibility. Is that possible?}@* | |
4322 @c | |
4323 @cindex @code{make-indirect-buffer} | |
4324 @cindex indirect buffers | |
4325 In GNU Emacs, you may use @emph{indirect buffers} which do exactly this. | |
4326 See the documentation on the command @code{make-indirect-buffer}. In | |
4327 XEmacs, this is currently not possible because of the different outline | |
4328 implementation. | |
4329 | |
4330 @item @b{When I export my TODO list, every TODO item becomes a | |
4331 separate section. How do I enforce these items to be exported as an | |
4332 itemized list?}@* | |
4333 @c | |
4334 If you plan to use ASCII or HTML export, make sure things you want to | |
4335 be exported as item lists are level 4 at least, even if that does mean | |
4336 there is a level jump. For example: | |
4337 | |
4338 @example | |
4339 * Todays top priorities | |
4340 **** TODO write a letter to xyz | |
4341 **** TODO Finish the paper | |
4342 **** Pick up kids at the school | |
4343 @end example | |
4344 | |
4345 Alternatively, if you need a specific value for the heading/item | |
4346 transition in a particular file, use the @samp{+OPTIONS} line to | |
4347 configure the @samp{H} switch. | |
4348 | |
4349 @example | |
4350 +OPTIONS: H:2; ... | |
4351 @end example | |
4352 | |
4353 @item @b{I would like to export only a subtree of my file to HTML. | |
4354 How?}@* | |
4355 @c | |
4356 @cindex exporting a subtree | |
4357 If you want to export a subtree, mark the subtree as region and then | |
4358 export. Marking can be done with @kbd{C-c @@ C-x C-x}, for example. | |
4359 | |
4360 @item @b{Org-mode takes over the S-cursor keys. I also want to use | |
4361 CUA-mode, is there a way to fix this conflict?}@* | |
4362 Yes, see @ref{Conflicts}. | |
4363 | |
4364 @item @b{One of my table columns has started to fill up with | |
4365 @samp{#ERROR}. What is going on?}@* | |
4366 @c | |
4367 Org-mode tried to compute the column from other fields using a | |
4368 formula stored in the @samp{#+TBLFM:} line just below the table, and | |
4369 the evaluation of the formula fails. Fix the fields used in the | |
4370 formula, or fix the formula, or remove it! | |
4371 | |
4372 @item @b{When I am in the last column of a table and just above a | |
4373 horizontal line in the table, pressing TAB creates a new table line | |
4374 @i{before} the horizontal line. How can I quickly move to the line | |
4375 @i{below} the horizontal line instead?}@* | |
4376 @c | |
4377 Press @key{down} (to get on the separator line) and then @key{TAB}. | |
4378 Or configure the variable @code{org-table-tab-jumps-over-hlines}. | |
4379 | |
4380 @item @b{How can I change the indentation of an entire table without | |
4381 fixing every line by hand?}@* | |
4382 @c | |
4383 @cindex indentation, of tables | |
4384 The indentation of a table is set by the first line. So just fix the | |
4385 indentation of the first line and realign with @key{TAB}. | |
4386 | |
4387 @item @b{Is it possible to include entries from org-mode files into my | |
4388 emacs diary?}@* | |
4389 @c | |
4390 Since the org-mode agenda is much more powerful and can contain the | |
4391 diary (@pxref{Calendar/Diary integration}), you should think twice | |
4392 before deciding to do this. Integrating Org-mode information into the | |
4393 diary is, however, possible. You need to turn on @emph{fancy diary | |
4394 display} by setting in @file{.emacs}: | |
4395 | |
4396 @lisp | |
4397 (add-hook 'diary-display-hook 'fancy-diary-display) | |
4398 @end lisp | |
4399 | |
4400 Then include the following line into your @file{~/diary} file, in | |
4401 order to get the entries from all files listed in the variable | |
4402 @code{org-agenda-files}: | |
4403 | |
4404 @example | |
4405 &%%(org-diary) | |
4406 @end example | |
4407 @noindent | |
4408 You may also select specific files with | |
4409 | |
4410 @example | |
4411 &%%(org-diary) ~/path/to/some/org-file.org | |
4412 &%%(org-diary) ~/path/to/another/org-file.org | |
4413 @end example | |
4414 | |
4415 If you now launch the calendar and press @kbd{d} to display a diary, the | |
4416 headlines of entries containing a timestamp, date range, schedule, or | |
4417 deadline referring to the selected date will be listed. Just like | |
4418 Org-mode's agenda view, the diary for @emph{today} contains additional | |
4419 entries for overdue deadlines and scheduled items. See also the | |
4420 documentation of the @command{org-diary} function. Under XEmacs, it is | |
4421 not possible to jump back from the diary to the org, this works only in | |
4422 the agenda buffer. | |
4423 | |
4424 @end enumerate | |
4425 | |
4426 | |
4427 @node Interaction, Bugs, FAQ, Miscellaneous | |
4428 @section Interaction with other packages | 4271 @section Interaction with other packages |
4429 @cindex packages, interaction with other | 4272 @cindex packages, interaction with other |
4430 Org-mode lives in the world of GNU Emacs and interacts in various ways | 4273 Org-mode lives in the world of GNU Emacs and interacts in various ways |
4431 with other code out there. | 4274 with other code out there. |
4432 | 4275 |
4433 @menu | 4276 @menu |
4434 * Extensions:: Third-party extensions for Org-mode | |
4435 * Cooperation:: Packages Org-mode cooperates with | 4277 * Cooperation:: Packages Org-mode cooperates with |
4436 * Conflicts:: Packages that lead to conflicts | 4278 * Conflicts:: Packages that lead to conflicts |
4437 @end menu | 4279 @end menu |
4438 | 4280 |
4439 @node Extensions, Cooperation, Interaction, Interaction | 4281 |
4440 @subsection Third-party extensions for Org-mode | 4282 @node Cooperation, Conflicts, Interaction, Interaction |
4441 | |
4442 The following extensions for Org-mode have been written by other people: | |
4443 | |
4444 @table @asis | |
4445 @cindex @file{org-mouse.el} | |
4446 @item @file{org-mouse.el} by Piotr Zielinski | |
4447 This package implements extended mouse functionality for Org-mode. It | |
4448 allows you to cycle visibility and to edit the document structure with | |
4449 the mouse. Best of all, it provides a context-sensitive menu on | |
4450 @key{mouse-3} that changes depending on the context of a mouse-click. | |
4451 @file{org-mouse.el} is freely available at @url{http://www.cl.cam.ac.uk/~pz215/files/org-mouse.el}. | |
4452 @cindex @file{org-publish.el} | |
4453 @item @file{org-publish.el} by David O'Toole | |
4454 This package provides facilities for publishing related sets of Org-mode | |
4455 files together with linked files like images as a webpages. It is | |
4456 highly configurable and can be used for other publishing purposes as | |
4457 well. As of Org-mode version 4.30, @file{org-publish.el} is part of | |
4458 the Org-mode distribution. It is not yet part of Emacs, however, due to | |
4459 a pending copyright assignment. In the mean time, @file{org-publish.el} | |
4460 can be downloaded from David's site: | |
4461 @url{http://dto.freeshell.org/e/org-publish.el}. | |
4462 @end table | |
4463 | |
4464 @node Cooperation, Conflicts, Extensions, Interaction | |
4465 @subsection Packages that Org-mode cooperates with | 4283 @subsection Packages that Org-mode cooperates with |
4466 | 4284 |
4467 @table @asis | 4285 @table @asis |
4468 @cindex @file{calc.el} | 4286 @cindex @file{calc.el} |
4469 @item @file{calc.el} by Dave Gillespie | 4287 @item @file{calc.el} by Dave Gillespie |
4536 Also this package uses the @kbd{S-<cursor>} keys, so everything written | 4354 Also this package uses the @kbd{S-<cursor>} keys, so everything written |
4537 in the paragraph above about CUA mode also applies here. | 4355 in the paragraph above about CUA mode also applies here. |
4538 @end table | 4356 @end table |
4539 | 4357 |
4540 | 4358 |
4541 @node Bugs, Acknowledgments, Interaction, Miscellaneous | 4359 @node Bugs, , Interaction, Miscellaneous |
4542 @section Bugs | 4360 @section Bugs |
4543 @cindex bugs | 4361 @cindex bugs |
4544 | 4362 |
4545 Here is a list of things that should work differently, but which I | 4363 Here is a list of things that should work differently, but which I |
4546 have found too hard to fix. | 4364 have found too hard to fix. |
4562 @item | 4380 @item |
4563 When the application called by @kbd{C-c C-o} to open a file link fails | 4381 When the application called by @kbd{C-c C-o} to open a file link fails |
4564 (for example because the application does not exist or refuses to open | 4382 (for example because the application does not exist or refuses to open |
4565 the file), it does so silently. No error message is displayed. | 4383 the file), it does so silently. No error message is displayed. |
4566 @item | 4384 @item |
4567 Plain list items should be able to hold a TODO item. Unfortunately this | |
4568 has so many technical problems that I will only consider this change for | |
4569 the next major release (5.0). | |
4570 @item | |
4571 The remote-editing commands in the agenda buffer cannot be undone with | 4385 The remote-editing commands in the agenda buffer cannot be undone with |
4572 @code{undo} called from within the agenda buffer. But you can go to | 4386 @code{undo} called from within the agenda buffer. But you can go to |
4573 the corresponding buffer (using @key{TAB} or @key{RET} and execute | 4387 the corresponding buffer (using @key{TAB} or @key{RET} and execute |
4574 @code{undo} there. | 4388 @code{undo} there. |
4575 @item | 4389 @item |
4576 Recalculating a table line applies the formulas from left to right. | 4390 Recalculating a table line applies the formulas from left to right. |
4577 If a formula uses @emph{calculated} fields further down the row, | 4391 If a formula uses @emph{calculated} fields further down the row, |
4578 multiple recalculation may be needed to get all fields consistent. | 4392 multiple recalculation may be needed to get all fields consistent. |
4579 @item | 4393 @item |
4580 Several words in a row may @b{*be made bold*}, but this does not work if | 4394 A single letter cannot be made bold, for example @samp{*a*}. |
4581 the string is distributed over two lines. | |
4582 @item | 4395 @item |
4583 The exporters work well, but could be made more efficient. | 4396 The exporters work well, but could be made more efficient. |
4584 @end itemize | 4397 @end itemize |
4585 | 4398 |
4586 @node Acknowledgments, , Bugs, Miscellaneous | 4399 |
4587 @section Acknowledgments | 4400 @node Extensions and Hacking, History and Acknowledgments, Miscellaneous, Top |
4401 @appendix Extensions, Hooks and Hacking | |
4402 | |
4403 This appendix lists extensions for Org-mode written by other authors. | |
4404 It also covers some aspects where users can easily extend the | |
4405 functionality of Org-mode. | |
4406 | |
4407 @menu | |
4408 * Extensions:: | |
4409 * Dynamic blocks:: | |
4410 @end menu | |
4411 | |
4412 @node Extensions, Dynamic blocks, Extensions and Hacking, Extensions and Hacking | |
4413 @section Third-party extensions for Org-mode | |
4414 | |
4415 The following extensions for Org-mode have been written by other people: | |
4416 | |
4417 @table @asis | |
4418 @cindex @file{org-mouse.el} | |
4419 @item @file{org-mouse.el} by Piotr Zielinski | |
4420 This package implements extended mouse functionality for Org-mode. It | |
4421 allows you to cycle visibility and to edit the document structure with | |
4422 the mouse. Best of all, it provides a context-sensitive menu on | |
4423 @key{mouse-3} that changes depending on the context of a mouse-click. | |
4424 @file{org-mouse.el} is freely available at @url{http://www.cl.cam.ac.uk/~pz215/files/org-mouse.el}. | |
4425 @cindex @file{org-publish.el} | |
4426 @item @file{org-publish.el} by David O'Toole | |
4427 This package provides facilities for publishing related sets of Org-mode | |
4428 files together with linked files like images as a webpages. It is | |
4429 highly configurable and can be used for other publishing purposes as | |
4430 well. As of Org-mode version 4.30, @file{org-publish.el} is part of the | |
4431 Org-mode distribution. It is not yet part of Emacs, however, a delay | |
4432 caused by the preparations for the 22.1 release. In the mean time, | |
4433 @file{org-publish.el} can be downloaded from David's site: | |
4434 @url{http://dto.freeshell.org/e/org-publish.el}. | |
4435 @cindex @file{org-blog.el} | |
4436 @item @file{org-blog.el} by David O'Toole | |
4437 A blogging plug-in for @file{org-publish.el}. | |
4438 @cindex @file{org-blogging.el} | |
4439 @item @file{org-blogging.el} by Bastien Guerry | |
4440 Publish Org-mode files as | |
4441 blogs. @url{http://www.cognition.ens.fr/~guerry/org-blogging.html}. | |
4442 @end table | |
4443 | |
4444 @node Dynamic blocks, , Extensions, Extensions and Hacking | |
4445 @section Dynamic blocks | |
4446 | |
4447 Org-mode documents can contain @emph{dynamic blocks}. These are | |
4448 specially marked regions that are updates by some user-written | |
4449 function. A good example for such a block is the clock table inserted | |
4450 by the command @kbd{C-c C-x C-r} (@pxref{Clocking work time}). | |
4451 | |
4452 Dynamic block are enclosed by a BEGIN-END structure that assigns a name | |
4453 to the block and can also specify parameters for the function producing | |
4454 the content of the block. | |
4455 | |
4456 @example | |
4457 #+BEGIN: myblock :parameter1 value1 :parameter2 value2 ..... | |
4458 | |
4459 #+END: | |
4460 @end example | |
4461 | |
4462 Dynamic blocks are updated with the following commands | |
4463 | |
4464 @table @kbd | |
4465 @kindex C-c C-x C-u | |
4466 @item C-c C-x C-u | |
4467 Update dynamic block at point. | |
4468 @kindex C-u C-c C-x C-u | |
4469 @item C-u C-c C-x C-u | |
4470 Update all dynamic blocks in the current file. | |
4471 @end table | |
4472 | |
4473 Updating a dynamic block means to remove all the text between BEGIN and | |
4474 END, parse the BEGIN line for parameters and then call the specific | |
4475 writer function for this block to insert the new content. For a block | |
4476 with name @code{myblock}, the writer function is | |
4477 @code{org-dblock-write:myblock} with as only parameter a property list | |
4478 with the parameters given in the begin line. Here is a trivial example | |
4479 of a block that keeps track of when the block update function was last | |
4480 run: | |
4481 | |
4482 @example | |
4483 #+BEGIN: block-update-time :format "on %m/%d/%Y at %H:%M" | |
4484 | |
4485 #+END: | |
4486 @end example | |
4487 | |
4488 @noindent | |
4489 The corresponding block writer function could look like this: | |
4490 | |
4491 @lisp | |
4492 (defun org-dblock-write:date-and-time (params) | |
4493 (let ((fmt (or (plist-get params :format) "%d. %m. %Y"))) | |
4494 (insert "Last block update at: " | |
4495 (format-time-string fmt (current-time))))) | |
4496 @end lisp | |
4497 | |
4498 If you want to make sure that all dynamic blocks are always up-to-date, | |
4499 you could add the function @code{org-update-all-dblocks} to a hook, for | |
4500 example @code{before-save-hook}. @code{org-update-all-dblocks} is | |
4501 written in a way that is does nothing in buffers that are not in Org-mode. | |
4502 | |
4503 | |
4504 @node History and Acknowledgments, Index, Extensions and Hacking, Top | |
4505 @appendix History and Acknowledgments | |
4588 @cindex acknowledgments | 4506 @cindex acknowledgments |
4507 @cindex history | |
4589 @cindex thanks | 4508 @cindex thanks |
4590 | 4509 |
4591 Org-mode was created by @value{AUTHOR}, who still maintains it at the | 4510 Org-mode was conceived in 2003 out of frustration over the user |
4592 Org-mode homepage @uref{http://www.astro.uva.nl/~dominik/Tools/org/}. | 4511 interface of the emacs outline-mode. The first driver was simply to |
4593 The following people (in alphabetic order) have helped the development | 4512 make working with an outline tree possible without having to remember |
4594 along with ideas, suggestions and patches. Many thanks to all of you, | 4513 more than 10 commands just for hiding and unhiding parts of the outline |
4595 Org-mode would not be what it is without your input. | 4514 tree, and to allow to restructure a tree easily. Visibility cycling and |
4515 structure editing were originally implemented in the package | |
4516 @file{outline-magic.el}, but quickly moved to the more general | |
4517 @file{org.el}. TODO entries and table support were added relatively | |
4518 quickly, and pointed to the two main drivers of Org-mode: Creating a | |
4519 new plain text mode with intuitive editing features, and to | |
4520 incorporate project planning functionality directly into a notes file. | |
4521 | |
4522 Since the first release, hundreds of emails either directly to me or | |
4523 later on @code{emacs-orgmode@@gnu.org} have been a constant source of | |
4524 bug reports, feedback and new ideas. While I cannot mention everyone, I | |
4525 try to keep here a list of the people who had significant | |
4526 influence in shaping one or more aspects of Org-mode. Many thanks to | |
4527 all of you. If I have forgotten someone, please accept my apologies. | |
4596 | 4528 |
4597 @itemize @bullet | 4529 @itemize @bullet |
4598 @item | 4530 @item |
4599 @i{Thomas Baumann} contributed the code for links to the MH-E email | 4531 @i{Thomas Baumann} contributed the code for links to the MH-E email |
4600 system. | 4532 system. |
4605 for Remember. | 4537 for Remember. |
4606 @item | 4538 @item |
4607 @i{Pavel Chalmoviansky} influenced the agenda treatment of items with | 4539 @i{Pavel Chalmoviansky} influenced the agenda treatment of items with |
4608 specified time. | 4540 specified time. |
4609 @item | 4541 @item |
4610 @i{Gregory Chenov} patched support for lisp forms into table | 4542 @i{Gregory Chernov} patched support for lisp forms into table |
4611 calculations and improved XEmacs compatibility. | 4543 calculations and improved XEmacs compatibility, in particular by porting |
4544 @file{nouline.el} to XEmacs. | |
4612 @item | 4545 @item |
4613 @i{Sacha Chua} suggested to copy some linking code from Planner. | 4546 @i{Sacha Chua} suggested to copy some linking code from Planner. |
4614 @item | 4547 @item |
4615 @i{Kees Dullemond} inspired the use of narrowed tabled columns. | 4548 @i{Kees Dullemond} inspired the use of narrowed tabled columns. |
4616 @item | 4549 @item |
4617 @i{Christian Egli} converted the documentation into TeXInfo format, | 4550 @i{Christian Egli} converted the documentation into TeXInfo format, |
4618 patched CSS formatting into the HTML exporter, and inspired the agenda. | 4551 patched CSS formatting into the HTML exporter, and inspired the agenda. |
4619 @item | 4552 @item |
4620 @i{Nic Ferrier} contributed mailcap and XOXO support. | 4553 @i{Nic Ferrier} contributed mailcap and XOXO support. |
4621 @item | 4554 @item |
4555 @i{Bastien Guerry} provoded extensive feedback. | |
4556 @item | |
4622 @i{Kai Grossjohann} pointed out key-binding conflicts caused by | 4557 @i{Kai Grossjohann} pointed out key-binding conflicts caused by |
4623 Org-mode. | 4558 Org-mode. |
4624 @item | 4559 @item |
4625 @i{Stefan Monnier} provided a patch to keep the Emacs-Lisp compiler | 4560 @i{Stefan Monnier} provided a patch to keep the Emacs-Lisp compiler |
4626 happy. | 4561 happy. |
4653 @i{Christian Schlauer} proposed angular brackets around links, among | 4588 @i{Christian Schlauer} proposed angular brackets around links, among |
4654 other things. | 4589 other things. |
4655 @item | 4590 @item |
4656 Linking to VM/BBDB/GNUS was inspired by @i{Tom Shannon}'s | 4591 Linking to VM/BBDB/GNUS was inspired by @i{Tom Shannon}'s |
4657 @file{organizer-mode.el}. | 4592 @file{organizer-mode.el}. |
4593 @c FIXME: | |
4594 @c @item | |
4595 @c @i{Daniel Sinder} came up with the idea if internal archiving my locking | |
4596 @c subtrees. | |
4658 @item | 4597 @item |
4659 @i{David O'Toole} wrote @file{org-publish.el} and drafted the manual | 4598 @i{David O'Toole} wrote @file{org-publish.el} and drafted the manual |
4660 chapter about publishing. | 4599 chapter about publishing. |
4661 @item | 4600 @item |
4662 @i{J@"urgen Vollmer} contributed code generating the table of contents | 4601 @i{J@"urgen Vollmer} contributed code generating the table of contents |
4682 work on a tty. | 4621 work on a tty. |
4683 @item | 4622 @item |
4684 @i{Piotr Zielinski} wrote @file{org-mouse.el} and showed how to follow | 4623 @i{Piotr Zielinski} wrote @file{org-mouse.el} and showed how to follow |
4685 links with mouse-1. | 4624 links with mouse-1. |
4686 @end itemize | 4625 @end itemize |
4687 | 4626 |
4688 @node Index, Key Index, Miscellaneous, Top | 4627 |
4689 @chapter Index | 4628 @node Index, Key Index, History and Acknowledgments, Top |
4629 @unnumbered Index | |
4690 | 4630 |
4691 @printindex cp | 4631 @printindex cp |
4692 | 4632 |
4693 @node Key Index, , Index, Top | 4633 @node Key Index, , Index, Top |
4694 @chapter Key Index | 4634 @chapter Key Index |