GNOME.org
 

[sawfish] Doc.

commit d0b4c86813b8e5fdd25d9ed1e63adfb99f3f790e
Author: Teika kazura <teika lavabit com>
Date:   Sat Nov 6 14:54:35 2010 +0900

    Doc.
    
    * Section of "popup menu" is rewritten.
    * "commandp" doc correction; t can be returned only for symbols.
    * Minor po/README update.
    * RPM spec file is declared to be unofficial.

 OPTIONS                  |    6 +-
 lisp/sawfish/wm/menus.jl |    9 +
 man/news.texi            |    8 +-
 man/sawfish.texi         |  382 ++++++++++++++++++++++++++++------------------
 po/README                |   18 ++-
 sawfish.spec.in          |    4 +
 6 files changed, 266 insertions(+), 161 deletions(-)
---
diff --git a/OPTIONS b/OPTIONS
index b8f2cec..3d447cd 100644
--- a/OPTIONS
+++ b/OPTIONS
@@ -178,8 +178,10 @@
 ;:  applications menu.")
 
 ;; (defvar-setq apps-menu-show-all nil
-;;    "Some entries are hidden from the menu, especially GNOME Apps like
-;;     eog, nautilus or evince. Settings this variable to 'nil will generate
+;;    "Some entries are hidden from the menu, for example GNOME specific
+;;     applications like eog, nautilus or evince.
+;;
+;;     Settings this variable to 'nil will generate
 ;;     a menu that honours NoDisplay, Hidden OnlyShowIn and NotShowIn fields.
 ;;     In other words it generates the same menu like GNOME or KDE.
 ;;     If this variable is set to 'maybe the NoDisplay and Hidden fields are
diff --git a/lisp/sawfish/wm/menus.jl b/lisp/sawfish/wm/menus.jl
index fc4b5b4..efa4165 100644
--- a/lisp/sawfish/wm/menus.jl
+++ b/lisp/sawfish/wm/menus.jl
@@ -86,6 +86,9 @@ before killing it.")
   (define menu-timer nil)
 
   (defvar window-ops-menu
+    ;; Mysterious underscore "_" before a string offers (human
+    ;; langugage) translation. The one inside of a string is
+    ;; a shortcut key.
     `((,(_ "Mi_nimize") iconify-window
        (insensitive . ,(lambda (w)
                          (not (or (window-iconifiable-p w)
@@ -147,9 +150,13 @@ before killing it.")
 
   (defvar window-ops-toggle-menu '())
 
+  ;; Window list menu
   (defvar window-menu nil)
 
   (defvar root-menu
+    ;; Mysterious underscore "_" before a stringoffers (human
+    ;; langugage) translation. The one inside of a string
+    ;; specifies shortcut key.
     `((,(_ "Sawfish Rootmenu"))
       ()
       (,(_ "_Windows") . window-menu)
@@ -251,6 +258,7 @@ before killing it.")
   (define (nicknamep arg) (fixnump arg))
   (define (nickname-ref nick) (table-ref nickname-table nick))
 
+  ;; Currently only use is to pass the window object.
   (define menu-args (make-fluid '()))
   (define where-is-fun (make-fluid '()))
 
@@ -310,6 +318,7 @@ before killing it.")
 	  (current-event-window orig-win))
 	(cond ((commandp result)
 	       (call-command result))
+	      ;; This supports (define (func) (interactive) ...)
 	      ((functionp result)
 	       (result))
 	      ((consp result)
diff --git a/man/news.texi b/man/news.texi
index 0601554..c4dd1a8 100644
--- a/man/news.texi
+++ b/man/news.texi
@@ -89,12 +89,18 @@ property of a window.
 @item Before you run @file{po/make-pot} to generate @file{sawfish.pot}, you
 now have to do @code{make all} at the top directory. Previously it was
 possible to produce wrong @file{sawfish.pot}.
- item Banished some bogus items in @file{sawfish.pot}
 @item The Spanish translation has been updated [gnome-es translation-team]
+ item Updated @file{sawfish.pot} and subsequently all @file{*.po}. Banished some bogus items in @file{sawfish.pot}. (Developer's personal extensios had sneaked into.)
 @end itemize
 
 @item Emacs sawfish-mode now indents @code{let-fluids} and let-loop correctly [Teika Kazura]
 
+ item Documentations [Teika kazura]
+ itemize
+ item Section on popup menus is rewritten. (@pxref{Popup Menus})
+ item Correction: The function @code{commandp} can only take symbols as its argument. (@pxref{Operations on Commands})
+ end itemize
+
 @item SawfishConfig ``Window rules'' section changes [Teika Kazura]
 
 Category @code{Placement} is renamed to @code{Geometry}.  The item
diff --git a/man/sawfish.texi b/man/sawfish.texi
index 1cf627d..4c8122c 100644
--- a/man/sawfish.texi
+++ b/man/sawfish.texi
@@ -5032,151 +5032,108 @@ structure @var{structure-name} (a symbol) when first referenced.  The
 @cindex Popup menus
 @cindex Menus, popup
 
-Popup menus are one of the two main methods through which the user may
-invoke Lisp code (the other is via keymaps, @pxref{Keymaps}). The
- code{popup-menu} function is invoked with a list of menu item
-definitions and the associated Lisp function to call for each item.
-This starts a subprocess to display the menu, then at a later date the
-chosen menu item is received and evaluated.
-
-Each menu item is specified by a list, the first element of which is a
-string providing the label for the menu item, the second element is a
-function to be called if that item is selected by the user. If this
-function has an interactive specification it will be invoked using the
- code{call-command} function, otherwise @code{funcall} will be used.
-Alternatively the second element may be a lisp form to evaluate. So,
-for example, a single-level menu could be defined by:
+Sawfish provieds @dfn{popup menus}. Each line of a popup menu is
+either an action or the parent of a submenu. Together with key and
+mouse bindings, popup menus offer a command invocation method to
+users.
 
- lisp
-(("Item 1" function-1)
- ("Item 2" function-2)
- ()
- ("Item 3" function-3))
- end lisp
-
- noindent
-The null item will create a separator line in the displayed menu.
-
-If the cdr of first element of any item is a symbol, then the rest of
-the item is defined by the value of the named variable. If this value
-is functional then the definition is found by calling the function.
+ menu
+* Ready-made Popups:: User options on ready-made popups.
+* Applications Menu:: 
+* Popup Definitions:: How to manually define popup menus.
+ end menu
 
-Consider the following definition:
+ node Ready-made Popups, Applications Menu, , Popup Menus
+ section Ready-made Popups
 
- lisp
-(("Workspaces" . workspace-menu)
- ("Windows" . window-menu)
- ("Programs" . apps-menu)
- ("Customize" . custom-menu)
- ("About..." (customize 'about))
- () ; Separation horizontal bar.
- ("Restart" restart)
- ("Quit" quit))
- end lisp
-
- noindent
-This is the old definition of Sawfish's root menu. We can see
-that four submenus are created dynamically by dereferencing variables
-(in fact, three of this variables contain functions)
-(@code{workspace-menu}, @code{window-menu}, @code{apps-menu} and
- code{custom-menu}). Note that these must be special variables,
-i.e. initially declared using the @code{defvar} special form.
-
-User can set @code{apps-menu} as they like. If it is unset, then
-Sawfish generates applications menu from @file{*.desktop} files. In
-that case, 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:
+First let's see popup menus available out-of-box. There are root menu,
+window operation menu, window list menu, applications menu, and
+others.
 
- lisp
-(("_xterm" (system "xterm &"))
- ("Emacs" (system "emacs &"))
- ("Firefox" (system "firefox &"))
- ("The _GIMP" (system "gimp &"))
- () ; Seperation horizontal bar
- )
- end lisp
+The @dfn{root menu} is obviously the most important one. Many things can be
+done from the root menu, including other menus invocation.  By
+default, you can call the root menu by middle-clicking the background
+screen, i.e., anywhere outside of all windows.
 
- noindent
-The @code{system} function simply executes its single argument using
- file{/bin/sh}. The underscore defines the keyboard shortcut.
+The @dfn{window operation menu} is what the name describes. You can call it
+from window's frames like buttons or the title bar, depending on
+themes.
 
-When displaying a menu item, it is possible to also display the
-corresponding keyboard shortcut in the menu.
+The @dfn{window list menu} lets you choose a window. When selected,
+that window is shown, raised, and focused.
 
- defvar menus-include-shortcuts
-When true, menu items also display key-binding information.  Defaults
-to false.
- end defvar
+The @dfn{applications menu} lets you invoke softwares. Many options are
+available, and it's explained in the next section. (@pxref{Applications
+Menu})
 
-The actual creation of a menu is performed by an auxiliary process,
-distributed with Sawfish.  Since the overhead of starting the menu
-subprocess may be noticeable on some systems, it is possible to leave
-it running between menu requests.
+Popup menu invocation functions can be called from keyboard or mouse.
 
- defvar menu-program
-Location of the program implementing Sawfish's menu interface.
- end defvar
+ defun popup-root-menu
+Display the main menu.
+ end defun
 
- defvar menu-program-stays-running
-This variable defines if, and for how long, the menu subprocess is
-allowed to remain executing for after the last menu has completed. If
- code{nil}, the program is terminated immediately, if @code{t} it is
-left running indefinitely, if an integer then the program will run for
-that many seconds (unless another menu is displayed).
- end defvar
+ defun popup-window-ops-menu
+Display the window operation menu. This has several
+bindings by default. In particular, clicking on a window's menu
+button displays this menu.
+ end defun
 
-The actual interface to invoke the external menu program is hidden in
-the @code{popup-menu} function.
+ defun popup-window-list-menu
+Display the menu containing the list of all open windows.
+ end defun
 
- defun popup-menu spec
-Displays a menu defined by the list of item definitions @var{spec}.
+ defun popup-apps-menu
+Popup the applications menu.
 @end defun
 
-In addition, Sawfish provides various canned menus, and functions to
-display those menus.
+Here are popup menu options.
 
- defvar popup-window-list-menu
-Display the menu containing the list of all open windows.
+ defvar menus-include-shortcuts
+When true, menu items also display the key-binding. Defaults
+to false.
 @end defvar
 
- defvar root-menu
-Contains the root menu definition.
- end defvar
+The actual creation of a popup menu is performed by an auxiliary
+process. By default, it stays after menu use is done, and reused
+at the next menu invocation.
 
- defun popup-root-menu
-Display the main menu.  By default, this is bound to Button2-click on
-the root window.
- end defun
+ defvar menu-program-stays-running
+Defines if and how long the menu program stays alive after the
+last menu has completed. If @code{nil}, the program is terminated
+immediately. This means each time the popup menu is invoked, menu
+program is executed.
 
- defvar apps-menu
-The variable containing the definition of the applications submenu of
-the root menu.  The default root menu includes this as a child menu.
+If it's @code{t} it is left running indefinitely, if an integer then
+the program may last for that many seconds.
 @end defvar
 
- defun popup-apps-menu
-Display the applications menu.
- end defun
+You can modify menus. @xref{Popup Definitions}.
+
+ node Applications Menu, Popup Definitions, Ready-made Popups, Popup Menus
+ section Applications Menu
+
+The applications menu lets you invoke installed applications. Sawfish
+generates applications menu from @file{*.desktop} files at Sawfish startup.
 
-Sawfish generates applications menu from @file{*.desktop} files.
+Options are described first.
 
 @defvar apps-menu-autogen
-If non-nil, @code{apps-menu} is automatically generated from
- code{user-apps-menu} and @file{*.desktop} files. If you set
- code{apps-menu}, then it won't happen anyway.
+If non-nil, the applications menu is automatically generated from
+ code{user-apps-menu} and @file{*.desktop} files, and stored in the
+variable @code{apps-menu}. Default is @code{t}.
 
-Default is @code{t}.
+If you set the applications menu manually to the variable
+ code{apps-menu}, then it won't happen anyway.
 @end defvar
 
- defvar user-apps-menu
-Your own application menu entries. It is followed by auto generated
-applications menu.
- end defvar
+ defvar apps-menu-show-all
+Some entries are hidden from the menu, for example GNOME specific
+applications like eog, nautilus or evince. If you want to have them
+added to your menu, set this to non-nil. Default is @code{nil}.
+See the file @file{OPTIONS} for alternate choices.
 
- 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}.
+Improvement of this option is planned. The variable name and
+choices may change.
 @end defvar
 
 @defvar desktop-directory
@@ -5184,48 +5141,173 @@ List of directories to look for *.desktop files. Default is
 @code{'("/usr/share/applications")}.
 @end defvar
 
+ defvar kde-desktop-directories
+KDE specific directories where *.desktop files are stored.
+ end defvar
+
 @defvar apps-menu-alphabetize
 Sort the generated apps menu alphabetically. Defaults to @code{t}.
 @end defvar
 
 @defvar apps-menu-lang
-Language for applications menu auto generation, in string. Default is
-set from locale.
+Human language for applications menu generation, in
+string, like ``en''. Default is set from the locale.
 @end defvar
 
- deffn Function update-apps-menu
- deffnx Comand update-apps-menu
+Here are functions for applications menu.
+
+ defun popup-apps-menu
+Display the applications menu.
+ end defun
+
+ defun update-apps-menu
 Set @code{apps-menu} to @code{user-apps-menu}, and if
 @code{apps-menu-autogen} is non-nil, append the auto generated one.
- end deffn
-
- deffn Function generate-apps-menu
-Return the applications menu list, generated from @file{*.desktop} files.
- end deffn
+ end defun
 
- defun window-ops-menu
-The variable containing the definition of all window operations.
+ defun generate-apps-menu
+Return the applications menu (a list), generated from @file{*.desktop}
+files which can be set to @code{apps-menu}.
 @end defun
 
- defun popup-window-menu
-Display the menu listing all window operations.  This has several
-bindings by default.  In particular, clicking on a window's menu
-button displays this menu.
+You can prepend anything to the applications menu, by setting the
+variable @code{user-apps-menu}. An example definition:
+
+ lisp
+(("_xterm" (system "xterm &"))
+ ("Emacs" (system "emacs &"))
+ ("Firefox" (system "firefox &"))
+ ("The _GIMP" (system "gimp &"))
+ () ; Seperation horizontal bar
+ ) ;; Auto generated menu will follow.
+ end lisp
+
+ noindent
+The @code{system} function simply executes its single argument using
+ file{/bin/sh}. The underscore defines the keyboard shortcut.
+
+Or, if you set value to @code{apps-menu}, Sawfish doesn't generate
+applications menu from @file{*.desktop}.
+
+ defvar apps-menu
+The variable containing the definition of the applications menu. If
+you set this, it is exclusively used, and Sawfish doesn't generate
+its applications menu.
+ end defvar
+
+ defvar user-apps-menu
+Your own applications menu entries. In the applications menu, this is
+followed by auto generated applications menu.
+ end defvar
+
+ node Popup Definitions, , Applications Menu, Popup Menus
+ section Popup Definitions
+ cindex Popup definitions
+ cindex Definitions, popup
+
+Sawfish comes with ready-made popup menus. This section describes
+how you can modify them.
+
+An entire popup menu is specified by a list. Each element corresponds
+to a menu item, in the displayed order from top to bottom. Example:
+
+ lisp
+(("Item _1" command-1)   ;; list for a command.
+ ("Item _2" . submenu-2) ;; cons for a submenu.
+ ()                      ;; nil makes a seperator line
+ ("_xterm" (system "xterm &")) ;; lisp expression is possible too.
+ end lisp
+
+Each menu item is typically specified by a list with two elements.
+The first is the name; it's a string, and displayed in the menu.
+An underscore (_) before a character defines an accelerator, or
+a shortcut key.
+
+The second element specifies the action to take. Possible choices are:
+
+ table @asis
+ item Command
+If it's a command name (a symbol), then that command is invoked. 
+In the window operation menu, if that command takes a window as the
+argument, it's passed.
+
+ item Lisp expression
+If it's a lisp expression, then it's evaluated inside of the
+ code{user} module.
+
+ item Function
+If it's a function (a closure or a subr), then it's invoked with
+no argument.
+ end table
+
+ noindent
+If an item is nil (instead of a list with two elements), then it's
+printed as a seperator line.
+
+
+An item can invoke a submenu. In this case, the item is a cons. The
+car is the printed name. The cdr is a symbol which is the name of a
+variable. That variable specifies another menu's contents.  Or the
+variable refers to a function, it's invoked, and the return value is
+used. Notice that this variable has to be special, or dynamically
+scoped, so that its value can be seen inside of the involved module.
+
+It's possible to pass a list with more than two elements as an item,
+but it is not explained. (Read the code and please tell us the usage.)
+
+Let's see one more example:
+
+ lisp
+(("Workspaces" . workspace-menu)
+ ("Windows" . window-menu)
+ ("Programs" . apps-menu)
+ ("Customize" . custom-menu)
+ ("About..." (customize 'about))
+ () ; Separation horizontal bar.
+ ("Restart" restart)
+ ("Quit" quit))
+ end lisp
+
+ noindent
+This is the old definition of Sawfish's root menu. We can see that
+four submenus are created by seeing the value of variables.
+They contain functions, and they're invoked.
+
+ defun popup-menu spec
+Displays a menu defined by the list of item definitions @var{spec}.
 @end defun
 
+ defvar root-menu
+Contains the root menu definition.
+ end defvar
+
+ defvar window-ops-menu
+The variable containing the definition of all window operations.
+ end defvar
+
+Popup menu is made by making a seperate process.
+
+ defvar menu-program
+Location of the program implementing Sawfish's menu interface.
+ end defvar
+
+Mainly for developers, one more esoteric thing, ``toggle menu'', is
+explained.
+
 @defvar window-ops-toggle-menu
-A list of flags describing windows, e.g., ``sticky'' or ``shaded''.
-This list is displayed in a menu, and by selecting items in this menu
-a user can turn the flags on and off for a given window.
+The toggle type submenu of window operations, like ``sticky'' or
+``shaded''. By selecting items in this menu, a user can turn the flags
+on and off for a given window.
 @end defvar
 
 @defun add-window-menu-toggle label command &optional predicate
-Add additional flags to @code{window-ops-toggle-menu}.  The
- var{command} is a function (or a symbol pointing to a function) that
-gets run when the menu item is selected.  If @var{predicate} is
-non-nil, it must be a function taking a window as argument.  If
- var{predicate} return true, the menu item will have a check mark next
-to it.
+Add an item to @code{window-ops-toggle-menu}.  The @var{command} is a
+function (or a symbol pointing to a function) that gets run when the
+menu item is selected.
+
+If @var{predicate} is non-nil, it must be a function taking a window
+as argument.  If @var{predicate} return true, the menu item will have
+a check mark next to it.
 @end defun
 
 @node Events, Commands, Popup Menus, Top
@@ -5664,14 +5746,8 @@ this returns @code{nil} or @code{root}, the currently focused window.
 Once a command has been defined, we can extract certain information
 about it.
 
- defun commandp @var{object}
-This function returns @code{t} if its argument may be called interactively.
-If @var{object} is a function (i.e. a symbol or a lambda-expression) it
-is a command if it contains an interactive declaration
-
-The only other object which is a command is a function call form; the
-use of these types of commands is discouraged but they can be useful
-sometimes.
+ defun commandp @var{symbol}
+Returns @code{t} if @var{symbol} is a command name.
 @end defun
 
 @defun command-documentation name
@@ -5936,7 +6012,9 @@ Extract the owning window of the current X event (this is a window
 object, or the symbol @code{root} for the root window, or @code{nil}
 if there is no window or no event).  This is stored internally as the
 current event window, and returned.
- c FIXME-DLU: why does this function take a WIN parameter?
+
+If the optional argument @var{win} is a window, then it will be
+returned as the current event window.
 @end defun
 
 @defun last-event
@@ -6585,6 +6663,10 @@ When @var{action} is @code{reboot} or @code{halt},
 applied to each window to ensure we safely quit the current session.
 @end defun
 
+ defvar want-poweroff-menu
+If you don't use GNOME, KDE, nor XFCE, power off related actions
+are added under the root menu -> ``Sessions''.
+ end defvar
 
 @node Other Functions, , Sawfish Invocation Functions, Miscellaneous Functions
 @section Other Functions
diff --git a/po/README b/po/README
index d308de0..badbe7e 100644
--- a/po/README
+++ b/po/README
@@ -51,9 +51,10 @@ Update your language po file by:
 
 Editing
 -------
-Recommended tools are for example "poedit" and emacs "po-mode". The
-latter is included in the gettext package. Your distributor
-may ship it as a seperate package.
+Recommended tools are for example Gtranslator, KBabel or Lokalize.
+
+Old tools "poedit" and emacs "po-mode" are less preferable, but also
+available. The latter is included in the gettext package.
 
 Submission
 ----------
@@ -82,7 +83,7 @@ complicated manner.
 
 String origin
 -------------
-Where does the string come from? You may want to know it, for example,
+Where do strings come from? You may want to know it, for example,
 when you want to confirm the validity of a string marked "fuzzy".
 
 Sawfish extracts strings from lisp sources which are under lisp/, 
@@ -90,9 +91,9 @@ themes/*/theme.jl, and scripts/. (It seems that the extraction script
 uses C sources too, but the author of this README couldn't find
 strings from C. C sources are under src/, for your information.)
 
-In order to search the origin of a string, "ack" is helpful. (In
-Debian, it's call "ack-grep".) If you can use git, "git grep" is your
-friend.
+In order to search the origin of a string, "ack" is a helpful
+tool. (In Debian, it's call "ack-grep".) If you can use git, "git
+grep" is your friend.
 
 Command names are translated, too, but they are often brief and
 difficult to get the meaning, without reading the documentation of
@@ -107,7 +108,8 @@ page.
 
 Not all are translated
 ----------------------
-Please expand this list of untranslated strings.
+Please expand this list of untranslated strings. We don't know the
+exact status.
 
 * Event names like "Button1-Off". (This is difficult to support, so
   we won't fix it in near future.)
diff --git a/sawfish.spec.in b/sawfish.spec.in
index b60851b..e8690bb 100644
--- a/sawfish.spec.in
+++ b/sawfish.spec.in
@@ -1,3 +1,7 @@
+# This file in not an offical spec of any distributions.
+# Please read the changelog at the bottom, and send us a fix if it doesn't work.
+# The latest is available from:
+# http://git.gnome.org/browse/sawfish/tree/sawfish.spec.in
 Summary: An extensible window manager for the X Window System
 Name: sawfish
 Version: @version@
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]