[sawfish] Completed doc updates for applications menu.

[Christopher Bratusek <chrisb src gnome org>]

commit 0dd2a9cd0e42d6167e3077037d18ffd61d6eee24
Author: Teika kazura <teika lavabit com>
Date:   Mon Oct 19 17:50:05 2009 +0900

    Completed doc updates for applications menu.

 ChangeLog                        |    6 ++++
 OPTIONS                          |   44 +++++++++++++++++++--------------
 lisp/sawfish/wm/ext/apps-menu.jl |   14 +++++++----
 man/news.texi                    |    8 +++---
 man/sawfish.texi                 |   49 ++++++++++++++++++++++++++++++++-----
 5 files changed, 86 insertions(+), 35 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 804cbc7..d477cec 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2009-10-19  Teika kazura <teika lavabit com>
+	* OPTIONS
+	* lisp/sawfish/wm/ext/apps-menu.jl
+	* man/news.texi
+	* man/sawfish.texi: Completed doc updates for applications menu.
+
 2009-10-17  Christopher Bratusek <zanghar freenet de>
 	* lisp/sawfish/wm/ext/apps-menu.jl: removed dupped Development Category from Developmentmenu
 	                                    added Editors Category to Developmentmenu
diff --git a/OPTIONS b/OPTIONS
index 64b68fd..0a57ebc 100644
--- a/OPTIONS
+++ b/OPTIONS
@@ -22,8 +22,6 @@
 
 ;; Good luck!
 
-;; $Id: OPTIONS,v 1.5 2004/01/11 17:26:15 jsh Exp $
-
 ;; window animation options
 
 ;;  (define-special-variable default-window-animator 'none
@@ -161,11 +159,36 @@
 ;;  (define-special-variable window-ops-toggle-menu)
 ;;  (define-special-variable window-menu)
 ;;  (define-special-variable root-menu)
+
+;;  Probably you want to set `user-apps-menu', instead of `apps-menu'.
+;;  See below.
 ;;  (define-special-variable apps-menu)
 
 ;;  (define-special-variable custom-menu-includes-all-settings t
 ;;    "When non-nil, the custom menu includes the `All settings' item.")
 
+;; Applications menu options
+;;  (define-special-variable apps-menu-autogen t
+;;   "If non-nil, `apps-menu' is automatically generated from *.desktop files.")
+
+;;  (define-special-variable user-apps-menu '()
+;;    "Your own `apps-menu' entries. It is followed by auto generated
+;:  applications menu.")
+
+;; (define-special-variable apps-menu-ignore-no-display nil
+;;    "Some entries are hidden from the menu, especially GNOME Apps like
+;;  eog, nautilus or evince. If you want to have them added to your menu,
+;;  set this to non-nil.")
+
+;; (define-special-variable desktop-directory '("/usr/share/applications")
+;;   "List of directories to look for *.desktop files")
+
+;; (define-special-variable apps-menu-lang nil
+;;   "Language for applications menu, in string. Default is set from locale.")
+
+;; (define-special-variable apps-menu-alphabetize 't
+;;   "Sort the apps menu alphabetically.")
+
 ;; window placement options
 
 ;;  (define-special-variable place-window-mode 'top-left
@@ -634,23 +657,6 @@
 ;; (define-special-variable infinite-desktop.stop-at-workspace-borders nil
 ;;   "Stop scrolling at workspace borders (Fixes warp-to-window bugs).")
 
-;; fdo-menu options
-
-;; (define-special-variable apps-menu-lang nil
-;;   "Language for applications menu, in string. Default is set from locale.")
-
-;; (define-special-variable desktop-directory '("/usr/share/applications")
-;;   "List of directories to look for .desktop files")
-
-;; (define-special-variable apps-menu-ignore-no-display nil
-;;   "Wether to ignore the `NoDisplay' setting")
-
-;; (define-special-variable apps-menu-alphabetize 't
-;;   "Wether to alphabetically sort menuentries")
-
-;; (define-special-variable apps-menu-autogen t
-;;   "If non-nil, `apps-menu' is automatically generated from *.desktop files.")
-
 ;; view-clipboard options
 
 ;; (require 'sawfish.wm.commands.user)
diff --git a/lisp/sawfish/wm/ext/apps-menu.jl b/lisp/sawfish/wm/ext/apps-menu.jl
index 4035792..0b64912 100644
--- a/lisp/sawfish/wm/ext/apps-menu.jl
+++ b/lisp/sawfish/wm/ext/apps-menu.jl
@@ -49,20 +49,23 @@
   (define-structure-alias apps-menu sawfish.wm.ext.apps-menu)
 
   ;; User Options
-  ;; Docstrings would be nice.
+  (defvar apps-menu-autogen t
+    "If non-nil, `apps-menu' is automatically generated from *.desktop files.")
+
   (defvar user-apps-menu '()
     "Your own `apps-menu' entries. It is followed by auto generated
 applications menu.")
 
-  (defvar desktop-directory '("/usr/share/applications"))
   (defvar apps-menu-ignore-no-display nil
     "Some entries are hidden from the menu, especially GNOME Apps like
 eog, nautilus or evince. If you want to have them added to your menu,
 set this to non-nil.")
+
+  (defvar desktop-directory '("/usr/share/applications")
+    "List of directories to look for *.desktop files."
+
   (defvar apps-menu-alphabetize t
     "Sort the apps menu alphabetically.")
-  (defvar apps-menu-autogen t
-    "If non-nil, `apps-menu' is automatically generated from *.desktop files.")
   (defvar apps-menu-lang nil
     "Language for applications menu, in string. Default is set from locale.")
 
@@ -365,7 +368,8 @@ exile it."
 	(fix-cats menu-cat-alist))))
 
   (define (init-apps-menu)
-    "If `apps-menu' is nil, then call `update-apps-menu'."
+    "If `apps-menu' is nil, then call `update-apps-menu'. This function
+is intended to be called during Sawfish initialization."
     (unless apps-menu
       (update-apps-menu)))
 
diff --git a/man/news.texi b/man/news.texi
index 0e77d3a..c953f05 100644
--- a/man/news.texi
+++ b/man/news.texi
@@ -104,10 +104,10 @@ Position parameters can be negative [Christopher Bratusek, Teika Kazura]
 @item New application menu [Matthew Love, Timo Korvola]
 
 Sawfish now generates application menu automatically, by reading
- file{/usr/share/applications/*.desktop} files. (Technically,
-specifications of these files are defined by freedesktop.org.)
-
-This is done only if you don't set value of the variable @code{apps-menu}.
+ file{/usr/share/applications/*.desktop} files. If you set
+ code{apps-menu}, then it won't be done. If you like to have both your
+own applications menu and auto generated one, then set your own in
+ code{user-apps-menu} instead of @code{apps-menu}.
 
 Root menu is revamped, too. [Christopher Bratusek]
 
diff --git a/man/sawfish.texi b/man/sawfish.texi
index ff2e3d3..6c00f99 100644
--- a/man/sawfish.texi
+++ b/man/sawfish.texi
@@ -4817,17 +4817,16 @@ three of this variables contain functions) (@code{workspace-menu},
 these must be special variables, i.e. initially declared using the
 @code{defvar} special form.
 
-The @code{apps-menu} variable can thus be used to redefine the
-applications menu. The default definition is as follows:
+Sawfish generates applications menu from @file{*.desktop} files.
+User can use @code{user-apps-menu} variable to define their own
+applications menu, and it is appended by auto generated one.
+Example of @code{user-apps-menu} definition can be as follows:
 
 @lisp
 (("xterm" (system "xterm &"))
  ("Emacs" (system "emacs &"))
- ("Netscape" (system "netscape &"))
- ("The GIMP" (system "gimp &"))
- ("XFIG" (system "xfig &"))
- ("GV" (system "gv &"))
- ("xcalc" (system "xcalc &")))
+ ("Firefox" (system "firefox &"))
+ ("The GIMP" (system "gimp &")))
 @end lisp
 
 @noindent
@@ -4887,6 +4886,42 @@ the root menu.  The default root menu includes this as a child menu.
 Display the applications menu.
 @end defun
 
+Sawfish generates applications menu from @file{*.desktop} files.
+
+ defvar apps-menu-autogen
+If non-nil, `apps-menu' is automatically generated from *.desktop files.
+Default is @code{t}.
+ end defvar
+
+ defvar user-apps-menu
+Your own `apps-menu' entries. It is followed by auto generated
+applications menu.
+ end defvar
+
+ defvar apps-menu-ignore-no-display
+Some entries are hidden from the menu, especially GNOME Apps like
+eog, nautilus or evince. If you want to have them added to your menu,
+set this to non-nil. Default is @code{nil}.
+ end defvar
+
+ defvar desktop-directory
+List of directories to look for *.desktop files. Default is
+ code{'("/usr/share/applications")}.
+ end defvar
+
+ defvar apps-menu-alphabetize
+Sort the apps menu alphabetically. Defaults to @code{t}.
+ end defvar
+
+ defvar apps-menu-lang
+Language for applications menu, in string. Default is set from locale.
+ end defvar
+
+ deffn Comand update-apps-menu
+Set `apps-menu' to `user-apps-menu', and if `apps-menu-autogen' is
+non-nil, append the auto generated one.
+ end deffn
+
 @defun window-ops-menu
 The variable containing the definition of all window operations.
 @end defun