[Emacs-diffs] Changes to emacs/man/org.texi

[Carsten Dominik]

Index: emacs/man/org.texi
diff -u emacs/man/org.texi:1.44 emacs/man/org.texi:1.45
--- emacs/man/org.texi:1.44     Thu Feb 23 10:55:52 2006
+++ emacs/man/org.texi  Wed Mar  1 07:08:45 2006
@@ -4,8 +4,8 @@
 @setfilename ../info/org
 @settitle Org Mode Manual
 
address@hidden VERSION 4.06
address@hidden DATE February 2006
address@hidden VERSION 4.07
address@hidden DATE March 2006
 
 @dircategory Emacs
 @direntry
@@ -188,9 +188,10 @@
 
 * Completion::                  M-TAB knows what you need
 * Customization::               Adapting Org-mode to your taste
+* Clean view::                  Getting rid of leading stars in the outline
+* TTY keys::                    Using Org-mode on a tty
 * FAQ::                         Frequently asked questions
 * Interaction::                 Other Emacs packages
-* TTY keys::                    Using Org-mode on a tty
 * Bugs::                        Things which do not work perfectly
 * Acknowledgments::             These people provided feedback and more
 
@@ -378,6 +379,9 @@
     more text
 * Another top level headline
 @end example
address@hidden Some people find the many stars too noisy and would prefer an
+outline that has whitespace followed by a single star as headline
+starters.  @ref{Clean view} describes a setup to realize this.
 
 @node Visibility cycling, Motion, Headlines, Document Structure
 @section Visibility cycling
@@ -512,7 +516,9 @@
 @item address@hidden
 Move subtree down (swap with next subtree of same level)
 @kindex C-c C-x C-w
address@hidden C-c C-x C-k
 @item C-c C-x C-w
address@hidden C-c C-x C-k
 Kill subtree, i.e. remove it from buffer but save in kill ring.
 @kindex C-c C-x M-w
 @item C-c C-x M-w
@@ -627,7 +633,7 @@
 If you wish to implement a tag system to cross-correlate information,
 this can be done as well in Org-mode.  Every headline can contain a
 list of tags, at the end of the headline.  Tags are normal words
-containing letters and @samp{_}, but no numbers.  Tags must be
+containing letters, numbers, @samp{_}, and @samp{@@}.  Tags must be
 preceded and followed by a single colon; like @samp{:WORK:}.  Several
 tags can be specified like @samp{:WORK:URGENT:}.
 
@@ -709,16 +715,20 @@
 editing such lists, and the HTML exporter (@pxref{Exporting}) does
 parse and format them.
 
-Org-mode knows ordered and unordered lists.  Unordered list items
-start with @samp{-}, @samp{+}, or @address@hidden using
address@hidden as a bullet, lines must be indented or they will be seen as
-top-level headlines.} as bullets.  Ordered list items start with
address@hidden or @samp{1)}.  Items belonging to the same list must have
-the same indentation on the first line.  In particular, if an ordered
-list reaches number @samp{10.}, also the 2--digit numbers must be
-written left-aligned with the other numbers in the list.  Indentation
-also determines the end of a list item.  It ends before the next line
-that is indented like the bullet/number, or less.  For example:
+Org-mode knows ordered and unordered lists.  Unordered list items start
+with @samp{-}, @samp{+}, or @address@hidden using @samp{*} as a
+bullet, lines must be indented or they will be seen as top-level
+headlines.  Also, when you are hiding leading stars to get a clean
+outline view, plain list items starting with a star are visually
+indistinguishable from true headlines.  In short: Even though @samp{*}
+is supported, it may be better to not use it for plain list items} as
+bullets.  Ordered list items start with @samp{1.} or @samp{1)}.  Items
+belonging to the same list must have the same indentation on the first
+line.  In particular, if an ordered list reaches number @samp{10.}, also
+the 2--digit numbers must be written left-aligned with the other numbers
+in the list.  Indentation also determines the end of a list item.  It
+ends before the next line that is indented like the bullet/number, or
+less.  For example:
 
 @example
 ** Lord of the Rings
@@ -1050,10 +1060,12 @@
 @cindex syntax, of formulas
 
 A formula can be any algebraic expression understood by the Emacs
address@hidden package.  Before evaluation by @code{calc-eval}
-(@pxref{Calling Calc from Your Lisp Programs,calc-eval,Calling calc
-from Your Lisp Programs,calc,GNU Emacs Calc Manual}), variable
-substitution takes place:
address@hidden package.  Note that @file{calc} has the slightly
+non-standard conversion that @samp{/} has lower precedence than
address@hidden, so that @samp{a/b*c} is interpreted as @samp{a/(b*c)}.  Before
+evaluation by @code{calc-eval} (@pxref{Calling Calc from Your Lisp
+Programs,calc-eval,Calling calc from Your Lisp Programs,calc,GNU Emacs
+Calc Manual}), variable substitution takes place:
 
 @example
   $        @r{refers to the current field}
@@ -1521,9 +1533,7 @@
 
 @cindex following links
 @kindex C-c C-o
address@hidden mouse-2
 @item C-c C-o
address@hidden mouse-2
 Open link at point.  This will launch a web browser for URLs (using
 @command{browse-url-at-point}), run vm/gnus/bbdb for the corresponding
 links, and execute the command in a shell link.  When the cursor is on
@@ -1542,8 +1552,11 @@
 shell link.
 
 @kindex mouse-2
address@hidden mouse-1
 @item mouse-2
-On links, @kbd{mouse-2} will open the link just like @kbd{C-c C-o} would.
address@hidden mouse-1
+On links, @kbd{mouse-2} will open the link just like @kbd{C-c C-o}
+would.  Under Emacs 22, also @kbd{mouse-1} will follow a link.
 
 @kindex mouse-3
 @item mouse-3
@@ -2487,10 +2500,13 @@
 Display original location and recenter that window.
 
 @kindex mouse-2
address@hidden mouse-1
 @kindex @key{TAB}
 @item mouse-2
address@hidden mouse-1
 @itemx @key{TAB}
-Go to the original location of the item in another window.
+Go to the original location of the item in another window.  Under Emacs
+22, also @kbd{mouse-1} will works for this.
 
 @kindex @key{RET}
 @itemx @key{RET}
@@ -2952,9 +2968,10 @@
 @menu
 * Completion::                  M-TAB knows what you need
 * Customization::               Adapting Org-mode to your taste
+* Clean view::                  Getting rid of leading stars in the outline
+* TTY keys::                    Using Org-mode on a tty
 * FAQ::                         Frequently asked questions
 * Interaction::                 Other Emacs packages
-* TTY keys::                    Using Org-mode on a tty
 * Bugs::                        Things which do not work perfectly
 * Acknowledgments::             These people provided feedback and more
 @end menu
@@ -3002,7 +3019,8 @@
 @end itemize
 @end table
 
address@hidden Customization, FAQ, Completion, Miscellaneous
+
address@hidden Customization, Clean view, Completion, Miscellaneous
 @section Customization
 @cindex customization
 @cindex options, for customization
@@ -3014,7 +3032,126 @@
 variables is available with @kbd{M-x org-customize}.  Or select
 @code{Browse Org Group} from the @code{Org->Customization} menu.
 
address@hidden FAQ, Interaction, Customization, Miscellaneous
address@hidden Clean view, TTY keys, Customization, Miscellaneous
address@hidden A cleaner outline view
address@hidden hiding leading stars
address@hidden clean outline view
+
+Some people find it noisy and distracting that the Org-mode headlines
+are starting with a potentially large number of stars.  For example in
+the example tree from @ref{Headlines}:
+
address@hidden
+* Top level headline
+** Second level
+*** 3rd level
+    some text
+*** 3rd level
+    more text
+* Another top level headline
address@hidden example
+
address@hidden
+Unfortunately this is deeply ingrained into the code of Org-mode and
+cannot be easily changed.  You can, however, modify the display in such
+a way that all leading stars become invisible and the outline more easy
+to read.  To do this, customize the variable
address@hidden like this:
+
address@hidden
+(setq org-hide-leading-stars t)
address@hidden lisp
+
address@hidden
+and restart emacs (this is necessary to make this change effective).
+The tree then becomes
+
address@hidden
+* Top level headline
+ * Second level
+  * 3rd level
+    some text
+  * 3rd level
+    more text
+* Another top level headline
address@hidden example
+
address@hidden
+Note that the leading stars are not truly replaced by whitespace, they
+are only fontified with the face @code{org-hide} that uses the
+background color as font color.  If are are not using either white or
+black background, you may have to customize this face to get the wanted
+effect.  Another possibility is to set this font such that the extra
+stars are @i{almost} invisible, for example using the color
address@hidden on a white background.
+
+Things become cleaner still if you skip all the even levels and use only
+odd levels 1, 3, 5..., effectively adding two stars to go from one
+outline level to the next:
+
address@hidden
+* Top level headline
+  * Second level
+    * 3rd level
+      some text
+    * 3rd level
+      more text
+* Another top level headline
address@hidden example
+
address@hidden
+In order to make the structure editing and export commands handle this
+convention correctly, use (again a restart of emacs will be needed)
+
address@hidden
+(setq org-odd-levels-only t)
address@hidden lisp
+
address@hidden
+You can convert an Org-mode file from single-star-per-level to
+double-star-per-level convention with @kbd{M-x org-convert-to-odd-levels
+RET} in that file.  It is not possible to use this setting on a
+file-local basis, so you need to decide which format to use.
+
address@hidden TTY keys, FAQ, Clean view, Miscellaneous
address@hidden Using org-mode on a tty
address@hidden tty keybindings
+
+Org-mode uses a number of keys that are not accessible on a tty.  This
+applies to most special keys like cursor keys, @key{TAB} and
address@hidden, when these are combined with modifier keys like @key{Meta}
+and/or @key{Shift}.  Org-mode uses these bindings because it needs to
+provide keys for a large number of commands, and because these keys
+appeared particularly easy to remember.  In order to still be able to
+access the core functionality of Org-mode on a tty, alternative
+bindings are provided.  Here is a complete list of these bindings,
+which are obviously more cumbersome to use.  Note that sometimes a
+work-around can be better.  For example changing a time stamp is
+really only fun with @address@hidden keys.  On a tty you would
+rather use @kbd{C-c .}  to re-insert the timestamp.
+
address@hidden
address@hidden @columnfractions 0.15 0.2 0.2
address@hidden @b{Default} @tab @b{Alternative 1} @tab @b{Alternative 2}
address@hidden @address@hidden     @tab @kbd{C-u @key{TAB}}       @tab
address@hidden @address@hidden    @tab @kbd{C-c C-x l}           @tab 
@address@hidden @key{left}}
address@hidden @address@hidden  @tab @kbd{C-c C-x L}           @tab
address@hidden @address@hidden   @tab @kbd{C-c C-x r}           @tab 
@address@hidden @key{right}}
address@hidden @address@hidden @tab @kbd{C-c C-x R}           @tab
address@hidden @address@hidden      @tab @kbd{C-c C-x u}           @tab 
@address@hidden @key{up}}
address@hidden @address@hidden    @tab @kbd{C-c C-x U}           @tab
address@hidden @address@hidden    @tab @kbd{C-c C-x d}           @tab 
@address@hidden @key{down}}
address@hidden @address@hidden  @tab @kbd{C-c C-x D}           @tab
address@hidden @address@hidden     @tab @kbd{C-c C-x c}           @tab
address@hidden @address@hidden     @tab @kbd{C-c C-x m}           @tab 
@address@hidden @key{RET}}
address@hidden @address@hidden   @tab @kbd{C-c C-x M}           @tab
address@hidden @address@hidden    @tab @kbd{C-c C-x @key{left}}  @tab
address@hidden @address@hidden   @tab @kbd{C-c C-x @key{right}} @tab
address@hidden @address@hidden      @tab @kbd{C-c C-x @key{up}}    @tab
address@hidden @address@hidden    @tab @kbd{C-c C-x @key{down}}  @tab
address@hidden multitable
+
address@hidden FAQ, Interaction, TTY keys, Miscellaneous
 @section Frequently asked questions
 @cindex FAQ
 
@@ -3026,6 +3163,11 @@
 (add-to-list 'auto-mode-alist '("README$" . org-mode))
 @end example
 
address@hidden @b{All these stars are driving me mad, I just find the Emacs
+outlines unreadable. Can't you just put white space and a single star as a
+starter for address@hidden
+See @ref{Clean view}.
+
 @item @b{I would like to have two windows on the same Org-mode
 file, but with different outline visibility.  Is that address@hidden
 @cindex @code{make-indirect-buffer}
@@ -3138,15 +3280,23 @@
 @end enumerate
 
 
address@hidden Interaction, TTY keys, FAQ, Miscellaneous
address@hidden Interaction, Bugs, FAQ, Miscellaneous
 @section Interaction with other packages
 @cindex packages, interaction with other
 Org-mode can cooperate with the following packages:
 
 @table @asis
address@hidden @file{org-mouse.el}
address@hidden @file{org-mouse.el} by Piotr Zielinski
+This package implements extended mouse functionality for Org-mode.  It
+allows to cycle visibility and to edit the document structure with the
+mouse.  It also provides a context-sensitive menu that changes depending
+on the context of a mouse-click.  Use a search engine to find this
+package on the web.
 @cindex @file{table.el}
 @item @file{table.el} by Takaaki Ota
-Org mode cooperates with table.el, see @ref{table.el}.
+Org mode cooperates with table.el, see @ref{table.el}.  @file{table.el}
+is part of Emacs 22.
 @cindex @file{calc.el}
 @item @file{calc.el} by Dave Gillespie
 Org-mode uses the calc package for implementing spreadsheet
@@ -3189,6 +3339,7 @@
 @code{org-disputed-keys}.
 @item @file{remember.el} by John Wiegley
 Org mode cooperates with remember, see @ref{Remember}.
address@hidden is not part of Emacs, find it on the web.
 @cindex @file{planner.el}
 @item @file{planner.el} by John Wiegley
 Planner is another tool to plan work and keep track of tasks.  Planner
@@ -3197,48 +3348,11 @@
 display the agenda entries resulting from org files in day-pages of
 the planner.  This can be done through the diary of the calendar:
 Integrate org files into the diary as described above, and then turn
-on the diary support of planner.
+on the diary support of planner.  Planner is not part of Emacs, find it
+on the web.
 @end table
 
address@hidden TTY keys, Bugs, Interaction, Miscellaneous
address@hidden Using org-mode on a tty
address@hidden tty keybindings
-
-Org-mode uses a number of keys that are not accessible on a tty.  This
-applies to most special keys like cursor keys, @key{TAB} and
address@hidden, when these are combined with modifier keys like @key{Meta}
-and/or @key{Shift}.  Org-mode uses these bindings because it needs to
-provide keys for a large number of commands, and because these keys
-appeared particularly easy to remember.  In order to still be able to
-access the core functionality of Org-mode on a tty, alternative
-bindings are provided.  Here is a complete list of these bindings,
-which are obviously more cumbersome to use.  Note that sometimes a
-work-around can be better.  For example changing a time stamp is
-really only fun with @address@hidden keys.  On a tty you would
-rather use @kbd{C-c .}  to re-insert the timestamp.
-
address@hidden
address@hidden @columnfractions 0.15 0.2 0.2
address@hidden @b{Default} @tab @b{Alternative 1} @tab @b{Alternative 2}
address@hidden @address@hidden     @tab @kbd{C-u @key{TAB}}       @tab
address@hidden @address@hidden    @tab @kbd{C-c C-x l}           @tab 
@address@hidden @key{left}}
address@hidden @address@hidden  @tab @kbd{C-c C-x L}           @tab
address@hidden @address@hidden   @tab @kbd{C-c C-x r}           @tab 
@address@hidden @key{right}}
address@hidden @address@hidden @tab @kbd{C-c C-x R}           @tab
address@hidden @address@hidden      @tab @kbd{C-c C-x u}           @tab 
@address@hidden @key{up}}
address@hidden @address@hidden    @tab @kbd{C-c C-x U}           @tab
address@hidden @address@hidden    @tab @kbd{C-c C-x d}           @tab 
@address@hidden @key{down}}
address@hidden @address@hidden  @tab @kbd{C-c C-x D}           @tab
address@hidden @address@hidden     @tab @kbd{C-c C-x c}           @tab
address@hidden @address@hidden     @tab @kbd{C-c C-x m}           @tab 
@address@hidden @key{RET}}
address@hidden @address@hidden   @tab @kbd{C-c C-x M}           @tab
address@hidden @address@hidden    @tab @kbd{C-c C-x @key{left}}  @tab
address@hidden @address@hidden   @tab @kbd{C-c C-x @key{right}} @tab
address@hidden @address@hidden      @tab @kbd{C-c C-x @key{up}}    @tab
address@hidden @address@hidden    @tab @kbd{C-c C-x @key{down}}  @tab
address@hidden multitable
-
address@hidden Bugs, Acknowledgments, TTY keys, Miscellaneous
address@hidden Bugs, Acknowledgments, Interaction, Miscellaneous
 @section Bugs
 @cindex bugs
 
@@ -3246,13 +3360,6 @@
 have found too hard to fix.
 
 @itemize @bullet
address@hidden @item
address@hidden If you call @code{fill-paragraph} (bound to @kbd{M-q}) in a 
table, the
address@hidden filling is correctly disabled.  However, if some text directly
address@hidden (without an empty line in between) precedes or follows a table, 
calling
address@hidden @code{fill-paragraph} in that text will also fill the table like
address@hidden normal text.  Also, @code{fill-region} does bypass the
address@hidden @code{fill-paragraph} code and will fill tables like normal text.
 @item
 Text in an entry protected with the @samp{QUOTE} keyword should not
 autowrap.
@@ -3261,6 +3368,10 @@
 (for example because the application does not exits or refuses to open
 the file), it does so silently.  No error message is displayed.
 @item
+Plain list items should be able to hold a TODO item.  Unfortunately this
+has so many technical problems that I will only consider this change for
+the next major release (5.0).
address@hidden
 The remote-editing commands in the agenda buffer cannot be undone with
 @code{undo} called from within the agenda buffer.  But you can go to
 the corresponding buffer (using @key{TAB} or @key{RET} and execute
@@ -3276,11 +3387,9 @@
 However, from Org-mode's timeline and agenda buffers (created with
 @kbd{C-c C-r} and @kbd{C-c a}), things do work correctly.
 @item
-Linux should also have a default viewer application, using mailcap.
-Maybe we can use GNUS or VM mime code?  Or dired's guessing commands?
-Any hints (or even patches) are appreciated.
address@hidden
-When you write @samp{x = a /b/ c}, b will be exported in italics.
+You can only make a single word boldface or italic.  To emphasize
+several words in a row, each much have the emphasize markers, like in
address@hidden *bold* *words*}.
 @item
 The exporters work well, but could be made more efficient.
 @end itemize
@@ -3353,6 +3462,9 @@
 @item 
 Roland Winkler pointed out that additional keybindings are needed to
 use Org-mode on a tty.
address@hidden
+Piotr Zielinski wrote @file{org-mouse.el} and pointed out to me that
+Emacs 22 can be made to follow links using mouse-1 clicks.
 @c @item
 @c Nic Ferrier and Christian Egli implemented XML export.
 @end itemize