diff --git a/doc/orgguide.texi b/doc/orgguide.texi index e7ba1734c..eb11dd592 100644 --- a/doc/orgguide.texi +++ b/doc/orgguide.texi @@ -47,7 +47,9 @@ under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License.'' +is included in the section entitled ``GNU Free Documentation License'' +in the full Org manual, which is distributed together with the compact +guide. (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and modify this GNU manual.'' @@ -235,7 +237,8 @@ Miscellaneous Org is a mode for keeping notes, maintaining TODO lists, and doing project planning with a fast and effective plain-text system. It is also an -authoring and publishing system. +authoring and publishing system, and it supports working with source code for +literal programming and reproducible research. @i{This document is a much compressed derivative of the @uref{http://orgmode.org/index.html#sec-4_1, comprehensive Org-mode manual}. @@ -260,31 +263,31 @@ to the Emacs load path. To do this, add the following line to @file{.emacs}: (setq load-path (cons "~/path/to/orgdir/contrib/lisp" load-path)) @end smallexample -@noindent For speed you should byte-compile the Lisp files with the shell +@noindent If you have been using git or a tar ball to get Org, you need to +run the following command to generate autoload information. command: @smallexample -make +make autoloads @end smallexample @node Activation, Feedback, Installation, Introduction @section Activation -Add the following lines to your @file{.emacs} file. The last three lines +Add the following lines to your @file{.emacs} file. The last four lines define @emph{global} keys for some commands --- please choose suitable keys yourself. @smalllisp ;; The following lines are always needed. Choose your own keys. -(add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode)) ; not needed since Emacs 22.2 (add-hook 'org-mode-hook 'turn-on-font-lock) ; not needed when global-font-lock-mode is on (global-set-key "\C-cl" 'org-store-link) (global-set-key "\C-ca" 'org-agenda) (global-set-key "\C-cb" 'org-iswitchb) +(global-set-key "\C-cc" 'org-capture) @end smalllisp -With this setup, all files with extension @samp{.org} will be put -into Org mode. +Files with extension @samp{.org} will be put into Org mode automatically. @node Feedback, , Activation, Introduction @section Feedback @@ -833,17 +836,14 @@ manual}} @node TODO Items, Tags, Hyperlinks, Top @chapter TODO Items -Org mode does not maintain TODO lists as separate documents@footnote{Of -course, you can make a document that contains only long lists of TODO items, -but this is not required.}. Instead, TODO items are an integral part of the -notes file, because TODO items usually come up while taking notes! With Org -mode, simply mark any entry in a tree as being a TODO item. In this way, -information is not duplicated, and the entire context from which the TODO -item emerged is always present. +Org mode does not require TODO lists to live in separate documents. Instead, +TODO items are part of a notes file, because TODO items usually +come up while taking notes! With Org mode, simply mark any entry in a tree +as being a TODO item. In this way, information is not duplicated, and TODO +items remain in the context from which they emerged. -Of course, this technique for managing TODO items scatters them -throughout your notes file. Org mode compensates for this by providing -methods to give you an overview of all the things that you have to do. +Org mode providing methods to give you an overview of all the things that you +have to do, collected from many files. @menu * Using TODO states:: Setting and switching states @@ -872,8 +872,7 @@ The most important commands to work with TODO entries are: Rotate the TODO state of the current item among @smallexample -,-> (unmarked) -> TODO -> DONE --. -'--------------------------------' +(unmarked) -> TODO -> DONE -> (unmarked) @end smallexample The same rotation can also be done ``remotely'' from the timeline and @@ -900,33 +899,27 @@ option @code{org-todo-state-tags-triggers} for details. @node Multi-state workflows, Progress logging, Using TODO states, TODO Items @section Multi-state workflows -You can use TODO keywords to indicate different @emph{sequential} states -in the process of working on an item, for example: +You can use TODO keywords to indicate @emph{sequential} working progress +states: @smalllisp (setq org-todo-keywords '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED"))) @end smalllisp -The vertical bar separates the TODO keywords (states that @emph{need -action}) from the DONE states (which need @emph{no further action}). If -you don't provide the separator bar, the last state is used as the DONE -state. -With this setup, the command @kbd{C-c C-t} will cycle an entry from TODO -to FEEDBACK, then to VERIFY, and finally to DONE and DELEGATED. - -Sometimes you may want to use different sets of TODO keywords in -parallel. For example, you may want to have the basic -@code{TODO}/@code{DONE}, but also a workflow for bug fixing, and a -separate state indicating that an item has been canceled (so it is not -DONE, but also does not require action). Your setup would then look -like this: +The vertical bar separates the TODO keywords (states that @emph{need action}) +from the DONE states (which need @emph{no further action}). If you don't +provide the separator bar, the last state is used as the DONE state. With +this setup, the command @kbd{C-c C-t} will cycle an entry from TODO to +FEEDBACK, then to VERIFY, and finally to DONE and DELEGATED. Sometimes you +may want to use different sets of TODO keywords in parallel. For example, +you may want to have the basic @code{TODO}/@code{DONE}, but also a workflow +for bug fixing. Your setup would then look like this: @smalllisp (setq org-todo-keywords '((sequence "TODO(t)" "|" "DONE(d)") - (sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)") - (sequence "|" "CANCELED(c)"))) + (sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)"))) @end smalllisp The keywords should all be different, this helps Org mode to keep track of @@ -1030,8 +1023,7 @@ make a difference only in the agenda. Set the priority of the current headline. Press @samp{A}, @samp{B} or @samp{C} to select a priority, or @key{SPC} to remove the cookie. @c -@item S-@key{up} -@itemx S-@key{down} +@item S-@key{up}/@key{dwn} Increase/decrease priority of current headline @end table @@ -1070,7 +1062,6 @@ Here is an example of a checkbox list. - [ ] Peter - [X] Sarah - [X] order food - - [ ] think about what music to play @end smallexample Checkboxes work hierarchically, so if a checkbox item has children that @@ -1215,16 +1206,7 @@ In this example, @samp{@@read} is a @emph{group tag} for a set of three tags: @samp{@@read}, @samp{@@read_book} and @samp{@@read_ebook}. You can also use the @code{:grouptags} keyword directly when setting -@var{org-tag-alist}: - -@lisp -(setq org-tag-alist '((:startgroup . nil) - ("@@read" . nil) - (:grouptags . nil) - ("@@read_book" . nil) - ("@@read_ebook" . nil) - (:endgroup . nil))) -@end lisp +@var{org-tag-alist}, see the documentation of that variable. @kindex C-c C-x q @vindex org-group-tags @@ -1555,8 +1537,7 @@ Cave's Date and Time tutorial}@* An important part of any organization system is the ability to quickly capture new ideas and tasks, and to associate reference material with them. -Org defines a capture process to create tasks. It stores files related to a -task (@i{attachments}) in a special directory. Once in the system, tasks and +Org defines a capture process to create tasks. Once in the system, tasks and projects need to be moved around. Moving completed project trees to an archive file keeps the system compact and fast. @@ -1569,10 +1550,9 @@ archive file keeps the system compact and fast. @node Capture, Refile and copy, Capture - Refile - Archive, Capture - Refile - Archive @section Capture -Org's method for capturing new items is heavily inspired by John Wiegley -excellent @file{remember.el} package. It lets you store quick notes with -little interruption of your work flow. Org lets you define templates for new -entries and associate them with different targets for storing notes. +Org's lets you store quick notes with little interruption of your work flow. +You can define templates for new entries and associate them with different +targets for storing notes. @menu * Setting up a capture location:: Where notes will be stored @@ -1584,10 +1564,9 @@ entries and associate them with different targets for storing notes. @unnumberedsubsec Setting up a capture location The following customization sets a default target@footnote{Using capture -templates, you can define more fine-grained capture locations, see +templates, you get finer control over capture locations, see @ref{Capture templates}.} file for notes, and defines a global -key@footnote{Please select your own key, @kbd{C-c c} is only a suggestion.} -for capturing new stuff. +key for capturing new stuff. @example (setq org-default-notes-file (concat org-directory "/notes.org")) @@ -1599,14 +1578,13 @@ for capturing new stuff. @table @kbd @item C-c c -Start a capture process. You will be placed into a narrowed indirect buffer -to edit the item. +Start a capture process, placing you into a narrowed indirect buffer to edit. @item C-c C-c Once you are done entering information into the capture buffer, @kbd{C-c C-c} will return you to the window configuration before the capture process, so that you can resume your work without further distraction. @item C-c C-w -Finalize by moving the entry to a refile location (@pxref{Refile and copy}). +Finalize by moving the entry to a refile location (see section 9.2). @item C-c C-k Abort the capture process and return to the previous state. @end table @@ -1649,9 +1627,8 @@ possibilities, consult the manual for more. @smallexample %a @r{annotation, normally the link created with @code{org-store-link}} %i @r{initial content, the region when capture is called with C-u.} -%t @r{timestamp, date only} -%T @r{timestamp with date and time} -%u, %U @r{like the above, but inactive timestamps} +%t, %T @r{timestamp, date only, or date and time} +%u, %U @r{like above, but inactive timestamps} @end smallexample @node Refile and copy, Archiving, Capture, Capture - Refile - Archive @@ -1660,7 +1637,7 @@ possibilities, consult the manual for more. When reviewing the captured data, you may want to refile or copy some of the entries into a different list, for example into a project. Cutting, finding the right location, and then pasting the note is cumbersome. To simplify -this process, you can use the following special command: +this process, use the following commands: @table @kbd @item C-c M-x @@ -1691,8 +1668,7 @@ the archive file. @table @kbd @item C-c C-x C-a -Archive the current entry using the command specified in the variable -@code{org-archive-default-command}. +Archive the current entry using @code{org-archive-default-command}. @item C-c C-x C-s@ @r{or short} @ C-c $ Archive the subtree starting at the cursor position to the location given by @code{org-archive-location}. @@ -2698,9 +2674,9 @@ manual}@* @uref{http://orgmode.org/orgcard.pdf,Key reference card}} -@node GNU Free Documentation License, , Miscellaneous, Top -@appendix GNU Free Documentation License -@include doclicense.texi +@c @node GNU Free Documentation License, , Miscellaneous, Top +@c @appendix GNU Free Documentation License +@c @include doclicense.texi @bye