From: Chong Yidong Date: Thu, 29 Dec 2011 15:58:42 +0000 (+0800) Subject: Cleanups for the new Org section in the Emacs manual. X-Git-Tag: emacs-pretest-24.0.93~102 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=0ed49f9399f8865af366b7b8763aa07dd181f325;p=emacs.git Cleanups for the new Org section in the Emacs manual. * doc/emacs/text.texi (Org Mode): Copyedits. Refer to Outline Format for example. Add index entries. (Org Organizer, Org Authoring): Nodes renamed. Copyedits. --- diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog index 7857295de92..6e0819621a2 100644 --- a/doc/emacs/ChangeLog +++ b/doc/emacs/ChangeLog @@ -1,3 +1,9 @@ +2011-12-29 Chong Yidong + + * text.texi (Org Mode): Copyedits. Refer to Outline Format for + example. Add index entries. + (Org Organizer, Org Authoring): Nodes renamed. Copyedits. + 2011-12-26 Chong Yidong * dired.texi (Dired Enter, Misc Dired Features): Document diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi index 7f703fbaad0..f5f0ffe8ef4 100644 --- a/doc/emacs/emacs.texi +++ b/doc/emacs/emacs.texi @@ -548,6 +548,7 @@ Commands for Human Languages * Case:: Changing the case of text. * Text Mode:: The major modes for editing text files. * Outline Mode:: Editing outlines. +* Org Mode:: The Emacs organizer. * TeX Mode:: Editing input to the formatter TeX. * HTML Mode:: Editing HTML and SGML files. * Nroff Mode:: Editing input to the formatter nroff. diff --git a/doc/emacs/text.texi b/doc/emacs/text.texi index 37a85a89ea2..e4bc31e0266 100644 --- a/doc/emacs/text.texi +++ b/doc/emacs/text.texi @@ -1256,117 +1256,139 @@ automatically by putting this in your init file (@pxref{Init File}): @node Org Mode @section Org Mode -@kindex TAB @r{(Org Mode)} -@kindex S-TAB @r{(Org Mode)} @cindex organizer @cindex planner -@findex org-mode -@cindex fold -@cindex headline -@kindex M- @r{(Org Mode)} -@kindex M- @r{(Org Mode)} -@kindex M- @r{(Org Mode)} -@kindex M- @r{(Org Mode)} -@kindex S-M- @r{(Org Mode)} -@kindex S-M- @r{(Org Mode)} -@kindex S-M- @r{(Org Mode)} -@kindex S-M- @r{(Org Mode)} - -Org mode extends Outline mode to turn Emacs into an organizer and an -authoring system. +@findex Org mode +@findex mode, Org -When editing a file ending with the @file{.org} extension, Emacs -automatically uses @code{org-mode} as the major mode. In this mode, -headlines start with one (or more) leading star(s) and comments start -with the @code{#} character at the beginning of a line. - -@example -* This is the first headline -** This is a first sub-headline -* This is the second headline - -Some content here. +@findex org-mode + Org mode is a variant of Outline mode for using Emacs as an +organizer and/or authoring system. Files with names ending in the +extension @file{.org} are opened in Org mode (@pxref{Choosing Modes}). +To explicitly switch to Org mode, type @kbd{M-x org-mode}. -# Some comment here. -@end example + In Org mode, as in Outline mode, each entry has a heading line that +starts with one or more @samp{*} characters. @xref{Outline Format}. +In addition, any line that begins with the @samp{#} character is +treated as a comment. -From here, you can use Org mode as a simple outliner: @key{TAB} on a -headline will cycle through the various folding states of a subtree, -and @key{S-TAB} anywhere in the buffer will (un)fold the whole -structure. +@kindex TAB @r{(Org Mode)} +@findex org-cycle + Org mode provides commands for easily viewing and manipulating the +outline structure. The simplest of these commands is @key{TAB} +(@code{org-cycle}). If invoked on a heading line, it cycles through +the different visibility states of the subtree: (i) showing only that +heading line, (ii) showing only the heading line and the heading lines +of its direct children, if any, and (iii) showing the entire subtree. +If invoked in a body line, the global binding for @key{TAB} is +executed. -You can also manipulate the structure of your document by moving a -headline up and down with @key{M-} and @key{M-}, or by -promoting and demoting a headline with @key{M-} and -@key{M-}. If you want to act on the whole subtree (i.e. the -headline and its content, including other headlines), simply add the -@kbd{Shift} key and use @key{S-M-}, @key{S-M-}, -@key{S-M-} and @key{S-M-}. +@kindex S-TAB @r{(Org Mode)} +@findex org-shifttab + Typing @key{S-TAB} (@code{org-shifttab}) anywhere in an Org mode +buffer cycles the visibility of the entire outline structure, between +(i) showing only top-level heading lines, (ii) showing all heading +lines but no body lines, and (iii) showing everything. -For further details, see @ref{Document Structure,,,org, The Org Manual}. +@kindex M- @r{(Org Mode)} +@kindex M- @r{(Org Mode)} +@kindex M- @r{(Org Mode)} +@kindex M- @r{(Org Mode)} +@findex org-metaup +@findex org-metadown +@findex org-metaleft +@findex org-metaright + You can move an entire entry up or down in the buffer, including its +body lines and subtree (if any), by typing @kbd{M-} +(@code{org-metaup}) or @kbd{M-} (@code{org-metadown}) on the +heading line. Similarly, you can promote or demote a heading line +with @kbd{M-} (@code{org-metaleft}) and @kbd{M-} +(@code{org-metaright}). These commands execute their global bindings +if invoked on a body line. + + The following subsections give basic instructions for using Org mode +as an organizer and as an authoring system. @xref{Top,The Org Mode +Manual,,org, The Org Manual}, for details. @menu -* Org as an organizer:: Manage TODO lists and agendas -* Org as an authoring system:: Export to various formats +* Org Organizer:: Managing TODO lists and agendas. +* Org Authoring:: Exporting Org buffers to various formats. @end menu -@node Org as an organizer +@node Org Organizer @subsection Org as an organizer +@cindex TODO item +@cindex Org agenda -@cindex TODO keywords @kindex C-c C-t @r{(Org Mode)} +@findex org-todo +@vindex org-todo-keywords + You can tag an Org entry as a @dfn{TODO} item by typing @kbd{C-c +C-t} (@code{org-todo}) anywhere in the entry. This adds the keyword +@samp{TODO} to the heading line. Typing @kbd{C-c C-t} again switches +the keyword to @samp{DONE}; another @kbd{C-c C-t} removes the keyword +entirely, and so forth. You can customize the keywords used by +@kbd{C-c C-t} via the variable @code{org-todo-keywords}. + @kindex C-c C-s @r{(Org Mode)} @kindex C-c C-d @r{(Org Mode)} -@vindex org-todo-keywords -@findex org-todo +@findex org-schedule +@findex org-deadline + Apart from marking an entry as TODO, you can attach a date to it, by +typing @kbd{C-c C-s} (@code{org-schedule}) in the entry. This prompts +for a date by popping up the Emacs Calendar (@pxref{Calendar/Diary}), +and then adds the tag @samp{SCHEDULED}, together with the selected +date, beneath the heading line. The command @kbd{C-c C-d} +(@code{org-deadline}) has the same effect, except that it uses the tag +@code{DEADLINE}. + +@kindex C-c [ @r{(Org Mode)} +@findex org-agenda-file-to-front +@vindex org-agenda-files + Once you have some TODO items planned in an Org file, you can add +that file to the list of @dfn{agenda files} by typing @kbd{C-c [} +(@code{org-agenda-file-to-front}). Org mode is designed to let you +easily maintain multiple agenda files, e.g.@: for organizing different +aspects of your life. The list of agenda files is stored in the +variable @code{org-agenda-files}. + @findex org-agenda -@cindex scheduled -@cindex deadline -@cindex agenda - -Each headline can be turned into a TODO item calling @code{org-todo} -with @key{C-c C-t} anywhere on it. This will add the TODO keyword -@code{TODO}. Hit @key{C-c C-t} to cycle through the list of available -TODO keywords: you can configure the variable @code{org-todo-keywords} -to use your own list of keywords. - -Now that you have something to do, let's add a date to it: pressing -@key{C-c C-s} on a headline will add @code{SCHEDULED} below it, and -you will be prompted for a date through the calendar. @key{C-c C-d} -has the same effect, except that the item will have a @code{DEADLINE} -instead. - -Now that some TODO items are planned in the current file, add it to -the list of agenda files with @key{C-c [}. Calling the interactive -command @code{org-agenda} will prompt you for what you want to see: a -list of things to do this week, a list of TODO items with specific -keywords, etc. - -For further details, see @ref{TODO items,,,org, The Org Manual} and -@ref{Dates and times,,,org, The Org Manual}. - -@node Org as an authoring system + To view items coming from your agenda files, type @kbd{M-x +org-agenda}. This command prompts for what you want to see: a list of +things to do this week, a list of TODO items with specific keywords, +etc. +@ifnottex +@xref{Agenda Views,,,org, The Org Manual}, for details. +@end ifnottex + +@node Org Authoring @subsection Org as an authoring system -@cindex export -@findex org-export -@cindex publish -@cindex code block -@cindex quote +@cindex Org exporting -You may want to format your Org notes nicely and to prepare them for -export and publication. Org supports simple text formatting: +@findex org-export +@kindex C-c C-e @r{(Org mode)} + You may want to format your Org notes nicely and to prepare them for +export and publication. To export the current buffer, type @kbd{C-c +C-e} (@code{org-export}) anywhere in an Org buffer. This command +prompts for an export format; currently supported formats include +HTML, La@TeX{}, OpenDocument (@file{.odt}), and PDF. Some formats, +such as PDF, require certain system tools to be installed. + +@vindex org-publish-project-alist + To export several files at once to a specific directory, either +locally or over the network, you must define a list of projects +through the variable @code{org-publish-project-alist}. See its +documentation for details. + + Org supports a simple markup scheme for applying text formatting to +exported documents: @example - This text is /emphasized/ -- This item uses *a bold font* +- This text is *in bold* - This text is _underlined_ - This text uses =a teletype font= -@end example - -If a paragraph is a quote or an example, you can use specific -environments: -@example #+begin_quote ``This is a quote.'' #+end_quote @@ -1376,19 +1398,7 @@ This is an example. #+end_example @end example -These environments will be displayed in a specific way with respect -to the selected export/publish backend. - -To export the current buffer, press the @key{C-c C-e} key anywhere in -an Org buffer. Supported export formats include @code{HTML}, La@TeX{} -and @file{.odt} (OpenDocument format.) Depending on your system -installation, you can also directly export to @code{pdf}. - -To export several files at once to a specific directory either locally -or on the Internet, you will need to define a list of projects through -the variable @code{org-publish-project-alist}. - -For further details, see @ref{Exporting,,,org, The Org Manual} and + For further details, see @ref{Exporting,,,org, The Org Manual} and @ref{Publishing,,,org, The Org Manual}. @node TeX Mode