Documentation fixes

ORGWEBPAGE/Changes.org

@@ -15,7 +15,6 @@
  :VISIBILITY: content
  :END:
 
-
 ** Incompatible changes
 
 *** New key for creating tags/property sparse trees
@@ -35,8 +34,30 @@ have been generated by uuidgen.  This means that id links from one
 file to another may stop working until all files have been
 exported again.
 
+*** In agenda, only priority cookies get the special face
+
+So far, an entire task would get a special face when
+=org-agenda-fontify-priorities= was set.  Now, the default value
+for this variable is the symbol =cookies=, which means that on
+the cookie is fontified.  Set it to =t= if you want the entire
+task headline to be fontified.
+
+
 ** Details
 
+*** Improved ASCII export of links
+
+ASCII export of links works now much better.  If a link has a
+link and a description part which are different, then the
+description will remain in the text while the link part will be
+moved to the end of the current section, before the next heading,
+as a footnote-like construct.
+
+Configure the variable =org-export-ascii-links-to-notes= if you
+prefer the links to be shown in the text.  In this case, Org will
+make an attempt to wrap the line which may have become
+significantly longer by showing the link.
+
 *** PDF export of agenda views
 
 Agenda views can now be exported to PDF files by writing them to
@@ -54,14 +75,14 @@ remote access, one of the problems can be that information stored
 in entries below the headline is not accessible in that format.
 
 You can now copy some of that information to the agenda view
-before exporting it.  For this you need set the variable 
+before exporting it.  For this you need to set the variable 
 =org-agenda-add-entry-text-maxlines= to a number greater than 0.
 
 #+begin_src emacs-lisp
 (setq org-agenda-add-entry-text-maxlines 20)
 #+end_src
 
-Or you can to this with the settings in a special agenda view,
+Or you can do this with the settings in a custom agenda view,
 for example
 
 #+begin_src emacs-lisp
@@ -71,25 +92,32 @@ for example
  ("agenda-today.pdf"))
 #+end_src
 
-*** Exporting of citations to LaTeX and HTML, using BibTeX
-    
-    Citations can now me made using BibTeX, and will be exported
-    to LaTeX and HTML.  This is implemented in a contributed
-    package by Taru Karttunen, /org-exp-bibtex.el/.  Kudos to
-    Taru for this really nice addition.
-
 *** Custom agenda commands can specify a filter preset
 
-If a custom agenda command specified a value for
+If a custom agenda command specifies a value for
 =org-agenda-filter-preset= in its options, the initial view of
 the agenda will be filterd by the specified tags.  Applying a
 filter with =/= will then always add to that preset filter,
 clearing the filter with =/ /= will set it back to the preset.
+Here is an example of a custom agenda view that will display the
+agenda, but hide all entries with tags =FLUFF= or =BLUFF=:
+
+#+begin_src emacs-lisp
+("A" "" agenda ""
+ ((org-agenda-filter-preset '("-FLUFF" "-BLUFF"))))
+#+end_src
 
 This is in response to a [[http://thread.gmane.org/gmane.emacs.orgmode/11752][thread on the mailing list]], started by
 Daniel Clemente and with great contributions by Bernt Hansen and
 Matt Lundin.
 
+*** Exporting of citations to LaTeX and HTML, using BibTeX
+    
+Citations can now me made using BibTeX, and will be exported to
+LaTeX and HTML.  This is implemented in a contributed package by
+Taru Karttunen, /org-exp-bibtex.el/.  Kudos to Taru for this
+really nice addition.
+
 *** Update of org2rem.el
 
 /org2rem.el/ has been updated significantly and now does a more
@@ -97,18 +125,15 @@ comprehensive job of exporting Org events to remind.
 
 Thanks to Sharad Pratap for this update.
 
-*** Improved ASCII export of links
+*** New div around the entire page in HTMP export
 
-ASCII export of links works now much better.  If a link has a
-link and a description part which are different, then the
-description will remain in the text while the link part will be
-moved to the end of the current section, before the next heading,
-as a footnote-like construct.
+A new =<div id=content>= is wrapped around the entire page,
+everything that is inside =<body>=.
 
-Configure the variable =org-export-ascii-links-to-notes= if you
-prefer the links to be shown in the text.  In this case, Org will
-make an attempt to wrap the line which may have become
-significantly longer by showing the link.
+This means that you need to update /org-info.js/ (if you have a
+local copy).  It will be safe todo so, because the new
+org-info.js still handles older pages correctly.  Thanks to
+Sebastian for making these changes so quicky.
 
 *** Clustering characters for undo
 
@@ -118,46 +143,14 @@ normally in Emacs, but the special binding of characters in
 Org-mode made this impossible until now.
 
 Thanks to Martin Pohlack for a patch which mimicks the behavior
-of the Emacs command loop for the Org version of self-insert.
-Note that this will not work in headlines and tables because
-typing there will do a lot of extra work.
+of the Emacs command loop for the Org version of
+=self-insert-command=.  Note that this will not work in headlines
+and tables because typing there will do a lot of extra work.
 
 There might be a small typing performance hit resulting from this
 change - please report in the mailing list if this is noticeable
 and annoying. 
 
-*** New reload command, with keyboard access
-
-There is now a special command to reload all Org Lisp files, so
-that you can stay in your Emacs session while pulling and
-compiling changes to Org.  The command to reload the compiled
-files (if available) is =C-c C-x r=.  If no compiled files are
-found, uncompiled ones will be loaded.  If you want to force
-loading of uncompiled code (great for producing backtraces), use
-a prefix arg: =C-u C-c C-x o=.  Both commands are available in
-the menu as well.
-
-This new command was inspired by one written earlier by Bernt
-Hansen.
-
-*** Macro replacement
-
-A string like ={{{ title }}}= will be replaced by the title of
-the document, ={{{ email }}}= by the email setting of the author
-and similarly for other export settings given in =#+...= lines.
-In addition to that, you can define an arbitrary number of
-macros, for example:
-
-#+begin_src org
-,#+MACRO: myaddress 41 Onestreet, 12345 New York, NY
-...
-,my address is {{{myaddress}}}, see you there.
-#+end_src
-
-Macro replacement is the very first thing that happens during
-export, and macros will be replaced even in source code and other
-protected regions.
-
 *** Separate settings for special C-a and C-e 
 
 The variable `org-special-ctrl-a/e' now allows separate settings
@@ -172,17 +165,17 @@ Thanks to Alan Davis for this proposal.
 *** orgstruct++-mode improvements
 
 In addition to =orgstruct-mode= which allows to use some Org-mode
-structure commands in other major modes, there is now a more
-invasive version of this mode: =orgstruct++-mode=.  This mode
-will import all paragraph and line wrapping variables into the
-major mode, so that, for example, during typing the auto-fill
-wrapping of items will work just like in Org-mode.  This change
-is not reversible, so turning off orgstruct++-mode will not
-remove these settings again. =orgstruct++-mode= is most useful in
-text modes like message-mode or =magit-log-edit-mode=.
-Furthermore, =orgstruct++-mode= will recognize plain list context
-not only in the first line of an item, but also further down, so
-that =M-RET= will correctly insert new items.
+structure commands in other major modes, there is a more invasive
+version of this mode: =orgstruct++-mode=.  This mode will import
+all paragraph and line wrapping variables into the major mode, so
+that, for example, during typing the auto-fill wrapping of items
+will work just like in Org-mode.  This change is not reversible,
+so turning off =orgstruct++-mode= will not remove these settings
+again. =orgstruct++-mode= is most useful in text modes like
+message-mode or =magit-log-edit-mode=.  Furthermore,
+=orgstruct++-mode= will recognize plain list context not only in
+the first line of an item, but also further down, so that =M-RET=
+will correctly insert new items.
 
 Thanks to Austin Frank for requesting some of these changes.
 
@@ -191,38 +184,66 @@ Thanks to Austin Frank for requesting some of these changes.
 =M-right= and =M-left= now do demote and promote all headlines in
 an active region.
 
-*** Turning off time-of-day search in headline
-
-Some people like to put a creation time stamp into a headline and
-then get confused if the time-of-day found in there shows up as
-the time-of-day of the deadline/scheduling entry for this
-headline.  The reason for this is that Org searches the headline
-for a free-format time when trying to sort the entry into the
-agenda, and that search accidentally finds the time in the
-creation time stamp or something else that happens to look like a
-time.  If this is more painful than useful for you, configure the
-new variable =org-agenda-search-headline-for-time=.
-
-*** The match syntax for tags/properties is now described in a single place
+*** Match syntax for tags/properties is now described in a single place
 
 The manual chapters about tags and about properties now only
 refer to the section about agenda views, where the general syntax
 of tag/property matches is described.
 
-*** New div around the entire page in HTMP export
+*** Macro replacement
 
-A new =<div id=content>= is wrapped around the entire page,
-everything that is inside =<body>=.
+A string like ={{{ title }}}= will be replaced by the title of
+the document, ={{{ email }}}= by the email setting of the author
+and similarly for other export settings given in =#+...= lines.
+In addition to that, you can define an arbitrary number of
+macros, for example:
 
-This means that you need to update /org-info.js/ (if you have a
-local copy).  Thanks to Sebastian for making these changes so
-quicky.
+#+begin_src org
+,#+MACRO: myaddress 41 Onestreet, 12345 New York, NY
+...
+,my address is {{{myaddress}}}, see you there.
+#+end_src
+
+Macro replacement is the very first thing that happens during
+export, and macros will be replaced even in source code and other
+protected regions.
+
+*** New reload command, with keyboard access
+
+There is now a special command to reload all Org Lisp files, so
+that you can stay in your Emacs session while pulling and
+compiling changes to Org.  The command to reload the compiled
+files (if available) is =C-c C-x r=.  If no compiled files are
+found, uncompiled ones will be loaded.  If you want to force
+loading of uncompiled code (great for producing backtraces), use
+a prefix arg: =C-u C-c C-x o=.  Both commands are available in
+the menu as well.
+
+This new command was inspired by one written earlier by Bernt
+Hansen.
 
 *** Faces for priority cookies can now be set freely
 
 The new variable =org-priority-faces= can be used to set faces
 for each priority.
 
+*** New key for creating tags/property sparse trees
+
+The key to produce a sparse tree matching tags and properties is
+now =C-c / m= instead of =C-c a T=.  This is more consistent with
+the =C-c a m= key for the corresponding agenda view.  =C-c / T=
+will still work for now, but it is no longer advertised in the
+documentation and may go away at any time in the future.
+
+*** IDs in HTML have "ID-" prefix when generated by uuidgen
+
+/uuidgen/ generates IDs that often start with a number, not a
+letter.  However, IDs and names in XHTML must start with a letter.
+Therefore, IDs in HTML files will now get an "ID-" prefix if they
+have been generated by /uuidgen/.  This means that id links from one
+file to another may stop working until all files have been
+exported again, so that both links and targets have the new prefix.
+
 *** In agenda, only priority cookies get the special face
 
 So far, an entire task would get a special face when
@@ -231,6 +252,19 @@ for this variable is the symbol =cookies=, which means that on
 the cookie is fontified.  Set it to =t= if you want the entire
 task headline to be fontified.
 
+*** Turning off time-of-day search in headline
+
+Some people like to put a creation time stamp into a headline and
+then get confused if the time-of-day found in there shows up as
+the time-of-day of the deadline/scheduling entry for this
+headline.  The reason for this is that Org searches the headline
+for a free-format time when trying to sort the entry into the
+agenda, and that search accidentally finds the time in the
+creation time stamp or something else that happens to look like a
+time.  If this is more painful than useful for you, configure the
+new variable =org-agenda-search-headline-for-time=.
+
+
 * Version 6.23
 ** Overview
 

doc/org.texi

@@ -6646,10 +6646,14 @@ that entry would be in the original buffer (taken from a property, from a
 
 @kindex /
 @item /
+@vindex org-agenda-filter-preset
 Filter the current agenda view with respect to a tag and/or effort estimates.
-The difference between this and a custom agenda commands is that filtering is
+The difference between this and a custom agenda command is that filtering is
 very fast, so that you can switch quickly between different filters without
-having to recreate the agenda.
+having to recreate the agenda@footnote{Custom commands can preset a filter by
+binding the variable @code{org-agenda-filter-preset} as an option.  This
+filter will then be applied to the view and presist as a basic filter through
+refreshes and more secondary filtering.}
 
 You will be prompted for a tag selection letter.  Pressing @key{TAB} at that
 prompt will offer use completion to select a tag (including any tags that do

lisp/org-agenda.el

@@ -644,14 +644,16 @@ option will be ignored.."
 
 (defcustom org-agenda-ndays 7
   "Number of days to include in overview display.
-Should be 1 or 7."
+Should be 1 or 7.
+Custom commands can set this variable in the options section."
   :group 'org-agenda-daily/weekly
   :type 'number)
 
 (defcustom org-agenda-start-on-weekday 1
   "Non-nil means, start the overview always on the specified weekday.
 0 denotes Sunday, 1 denotes Monday etc.
-When nil, always start on the current day."
+When nil, always start on the current day.
+Custom commands can set this variable in the options section."
   :group 'org-agenda-daily/weekly
   :type '(choice (const :tag "Today" nil)
 		 (number :tag "Weekday No.")))
@@ -711,7 +713,8 @@ and timeline buffers."
 	      (const :tag "Sunday" 0)))
 
 (defcustom org-agenda-include-diary nil
-  "If non-nil, include in the agenda entries from the Emacs Calendar's diary."
+  "If non-nil, include in the agenda entries from the Emacs Calendar's diary.
+Custom commands can set this variable in the options section."
   :group 'org-agenda-daily/weekly
   :type 'boolean)
 
@@ -869,7 +872,9 @@ categories by priority.
 
 Instead of a single list, this can also be a set of list for specific
 contents, with a context symbol in the car of the list, any of
-`agenda', `todo', `tags' for the corresponding agenda views."
+`agenda', `todo', `tags' for the corresponding agenda views.
+
+Custom commands can bind this variable in the options section."
   :group 'org-agenda-sorting
   :type `(choice
 	  (repeat :tag "General" ,org-sorting-choice)
@@ -955,7 +960,9 @@ the prefix, you could use:
   (setq org-agenda-prefix-format \"  %-11:c% s\")
 
 See also the variables `org-agenda-remove-times-when-in-prefix' and
-`org-agenda-remove-tags'."
+`org-agenda-remove-tags'.
+
+Custom commands can set this variable in the options section."
   :type '(choice
 	  (string :tag "General format")
 	  (list :greedy t :tag "View dependent"
@@ -2226,7 +2233,13 @@ Drawers will be excluded, also the line with scheduling/deadline info."
 (defvar org-agenda-columns-active nil)
 (defvar org-agenda-name nil)
 (defvar org-agenda-filter nil)
-(defvar org-agenda-filter-preset nil)
+(defvar org-agenda-filter-preset nil
+  "A preset of the tags filter used for secondary agenda filtering.
+This must be a list of strings, each string must be a single tag preceeded
+by \"+\" or \"-\".
+This variable should not be set directly, but agenda custom commands can
+bind it in the options section.")
+
 (defun org-prepare-agenda (&optional name)
   (setq org-todo-keywords-for-agenda nil)
   (setq org-done-keywords-for-agenda nil)
@@ -2562,7 +2575,8 @@ When EMPTY is non-nil, also include days without any entries."
 ;;; Agenda Daily/Weekly
 
 (defvar org-agenda-overriding-arguments nil) ; dynamically scoped parameter
-(defvar org-agenda-start-day nil) ; dynamically scoped parameter
+(defvar org-agenda-start-day nil  ; dynamically scoped parameter
+"Custom commands can set this variable in the options section.")
 (defvar org-agenda-last-arguments nil
   "The arguments of the previous call to org-agenda")
 (defvar org-starting-day nil) ; local variable in the agenda buffer
@@ -3102,7 +3116,9 @@ This is basically a temporary global variable that can be set and then
 used by user-defined selections using `org-agenda-skip-function'.")
 
 (defvar org-agenda-overriding-header nil
-  "When this is set during todo and tags searches, will replace header.")
+  "When this is set during todo and tags searches, will replace header.
+This variable should not be set directly, but custom commands can bind it
+in the options section.")
 
 (defun org-agenda-skip-subtree-when-regexp-matches ()
   "Checks if the current subtree contains match for `org-agenda-skip-regexp'.

lisp/org.el

@@ -1836,7 +1836,7 @@ also set this to a string to define the drawer of your choice.
 A value of t is also allowed, representing \"LOGBOOK\".
 
 If this variable is set, `org-log-state-notes-insert-after-drawers'
-will be ognored."
+will be ignored."
   :group 'org-todo
   :group 'org-progress
   :type '(choice
@@ -2008,7 +2008,9 @@ org-mode generates a time duration."
   "No. of days before expiration during which a deadline becomes active.
 This variable governs the display in sparse trees and in the agenda.
 When 0 or negative, it means use this number (the absolute value of it)
-even if a deadline has a different individual lead time specified."
+even if a deadline has a different individual lead time specified.
+
+Custom commands can set this variable in the options section."
   :group 'org-time
   :group 'org-agenda-daily/weekly
   :type 'number)