[Emacs-diffs] /srv/bzr/emacs/trunk r106744: Cleanups for the new Org section in the Emacs manual.

[Chong Yidong]

------------------------------------------------------------
revno: 106744
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Thu 2011-12-29 23:58:42 +0800
message:
  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.
modified:
  doc/emacs/ChangeLog
  doc/emacs/emacs.texi
  doc/emacs/text.texi

=== modified file 'doc/emacs/ChangeLog'
--- a/doc/emacs/ChangeLog       2011-12-26 10:36:41 +0000
+++ b/doc/emacs/ChangeLog       2011-12-29 15:58:42 +0000
@@ -1,3 +1,9 @@
+2011-12-29  Chong Yidong  <address@hidden>
+
+       * 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  <address@hidden>
 
        * dired.texi (Dired Enter, Misc Dired Features): Document

=== modified file 'doc/emacs/emacs.texi'
--- a/doc/emacs/emacs.texi      2011-12-25 14:16:00 +0000
+++ b/doc/emacs/emacs.texi      2011-12-29 15:58:42 +0000
@@ -548,6 +548,7 @@
 * 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.

=== modified file 'doc/emacs/text.texi'
--- a/doc/emacs/text.texi       2011-12-21 14:02:38 +0000
+++ b/doc/emacs/text.texi       2011-12-29 15:58:42 +0000
@@ -1256,117 +1256,139 @@
 
 @node Org Mode
 @section Org Mode
address@hidden TAB @r{(Org Mode)}
address@hidden S-TAB @r{(Org Mode)}
 @cindex organizer
 @cindex planner
address@hidden Org mode
address@hidden mode, Org
+
 @findex org-mode
address@hidden fold
address@hidden headline
+  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}.
+
+  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.
+
address@hidden TAB @r{(Org Mode)}
address@hidden 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.
+
address@hidden S-TAB @r{(Org Mode)}
address@hidden 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.
+
 @kindex M-<up> @r{(Org Mode)}
 @kindex M-<down> @r{(Org Mode)}
 @kindex M-<left> @r{(Org Mode)}
 @kindex M-<right> @r{(Org Mode)}
address@hidden S-M-<up> @r{(Org Mode)}
address@hidden S-M-<down> @r{(Org Mode)}
address@hidden S-M-<left> @r{(Org Mode)}
address@hidden S-M-<right> @r{(Org Mode)}
-
-Org mode extends Outline mode to turn Emacs into an organizer and an
-authoring system.
-
-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.
-
address@hidden
-* This is the first headline
-** This is a first sub-headline
-* This is the second headline
-
-Some content here.
-
-# Some comment here.
address@hidden example
-
-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.
-
-You can also manipulate the structure of your document by moving a
-headline up and down with @key{M-<up>} and @key{M-<down>}, or by
-promoting and demoting a headline with @key{M-<left>} and
address@hidden<left>}.  If you want to act on the whole subtree (i.e. the
-headline and its content, including other headlines), simply add the
address@hidden key and use @key{S-M-<up>}, @key{S-M-<down>},
address@hidden<left>} and @key{S-M-<right>}.
-
-For further details, see @ref{Document Structure,,,org, The Org Manual}.
address@hidden org-metaup
address@hidden org-metadown
address@hidden org-metaleft
address@hidden 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-<up>}
+(@code{org-metaup}) or @kbd{M-<down>} (@code{org-metadown}) on the
+heading line.  Similarly, you can promote or demote a heading line
+with @kbd{M-<left>} (@code{org-metaleft}) and @kbd{M-<left>}
+(@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
 
address@hidden Org as an organizer
address@hidden Org Organizer
 @subsection Org as an organizer
address@hidden TODO item
address@hidden Org agenda
 
address@hidden TODO keywords
 @kindex C-c C-t @r{(Org Mode)}
address@hidden org-todo
address@hidden 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
address@hidden 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
address@hidden 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)}
address@hidden org-todo-keywords
address@hidden org-todo
address@hidden org-schedule
address@hidden 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
address@hidden
+
address@hidden C-c [ @r{(Org Mode)}
address@hidden org-agenda-file-to-front
address@hidden 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
address@hidden scheduled
address@hidden deadline
address@hidden 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
address@hidden  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
address@hidden 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
address@hidden and times,,,org, The Org Manual}.
-
address@hidden 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.
address@hidden
address@hidden Views,,,org, The Org Manual}, for details.
address@hidden ifnottex
+
address@hidden Org Authoring
 @subsection Org as an authoring system
address@hidden export
address@hidden Org exporting
+
 @findex org-export
address@hidden publish
address@hidden code block
address@hidden quote
-
-You may want to format your Org notes nicely and to prepare them for
-export and publication.  Org supports simple text formatting:
address@hidden 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, address@hidden, OpenDocument (@file{.odt}), and PDF.  Some formats,
+such as PDF, require certain system tools to be installed.
+
address@hidden 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=
address@hidden example
-
-If a paragraph is a quote or an example, you can use specific
-environments:
-
address@hidden
+
 #+begin_quote
 ``This is a quote.''
 #+end_quote
@@ -1376,19 +1398,7 @@
 #+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}, address@hidden
-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