Manpage: FvwmAuto

configure.ac

@@ -1527,7 +1527,6 @@ dnl	bin/fvwm-menu-headlines.1
 dnl	bin/fvwm-menu-xlock.1
 dnl	bin/fvwm-perllib.1
 	bin/fvwm-root.1
-	modules/FvwmAuto/FvwmAuto.1
 	modules/FvwmBacker/FvwmBacker.1
 	modules/FvwmBanner/FvwmBanner.1
 	modules/FvwmButtons/FvwmButtons.1

modules/FvwmAuto/FvwmAuto.adoc

@@ -0,0 +1,139 @@
+FvwmAuto(1)
+===========
+:man source:   AsciiDoc
+:man version:  {revnumber}
+:man manual: FvwmAuto
+
+NAME
+----
+
+FvwmAuto - the fvwm auto-raise module
+
+SYNOPSIS
+--------
+[verse]
+Module FvwmAuto Timeout [-passid] [-menter|-menterleave|-mfocus]
+			[EnterCommand [LeaveCommand]]
+
+FvwmAuto can only be invoked by fvwm.  Command line invocation of FvwmAuto
+will not work.
+
+DESCRIPTION
+-----------
+       
+The FvwmAuto module is most often used to automatically raise focused windows.
+
+INVOCATION
+----------
+
+The Timeout argument is required. It specifies how long a window must
+retain the keyboard input focus before the command is executed. The
+delay is measured in milliseconds, and any integer greater than zero is
+valid.
+
+If the literal option '-passid' is given, the window id of the window
+just entered or left is appended to the command that is sent to fvwm.
+This can be used with the WindowId command of fvwm.
+
+The options '-menter', '-menterleave' and '-mfocus' influence the actions
+FvwmAuto reacts to.  No more than one of the options can be chosen.  In
+-mfocus mode, FvwmAuto raises the window that has the focus.  In
+-menter mode, FvwmAuto raises the window under the pointer when the
+pointer enters a window.  The LeaveCommand is executed on the window
+that was below the pointer before it entered the new window.  When the
+pointer leaves a window and enters the root window, the EnterCommand is
+executed too, but without a window to operate on.  In '-menterleave'
+mode, FvwmAuto works just like in '-menter' mode, but the LeaveCommand is
+also executed if the pointer moves out of a window but does not enter a
+new window.  The latter two modes of operation are useful with windows
+that do not accept the focus.
+
+Note: '-menterleave' mode can interfere with popup windows of some
+applications.  One example is the zoom menu of Ghostview.  Please do
+not complain about this to us - it is a bug in Ghostview.
+
+EnterCommand and LeaveCommand are optional.  EnterCommand is executed
+Timeout milliseconds after a window gets the input focus, LeaveCommand
+is executed Timeout milliseconds after the window has lost focus.  Note
+that you always should use the 'Silent' keyword before the command
+itself.  FvwmAuto prepends "Silent " to the command string on its own
+if yor forget this.  Without this prefix fvwm would ask you for a
+window to act on if the window has died before the command sent by
+FvwmAuto has been processed by fvwm.  This can for example happen with
+popup menus.
+
+"Silent Raise" is the default for EnterCommand, but any fvwm function
+is allowed. I would not use "Close" or "Destroy" with a low timeout,
+though.  The LeaveCommand can be handy for a tidy desktop.  Experiment
+with:
+
+-------------------------------------------------------------------------------
+Module FvwmAuto 0 Nop "Silent Lower"
+Module FvwmAuto 0 Nop "Silent Iconify"
+-------------------------------------------------------------------------------
+
+An example for auto raising windows with ClickToFocus:
+
+-------------------------------------------------------------------------------
+Style * ClickToFocus
+FvwmAuto 0 -menter "Silent Raise"
+-------------------------------------------------------------------------------
+
+An example for auto raising and lowering only some windows:
+
+-------------------------------------------------------------------------------
+# To start FvwmAuto:
+FvwmAuto 0 -passid -menter \
+"Silent selective_raiselower raise" \
+"Silent selective_raiselower lower"
+
+# And put this in your .fvwm2rc:
+AddToFunc selective_raiselower
++ I WindowId $1 (FvwmIconMan) $0
++ I WindowId $1 (FvwmButtons) $0
++ I WindowId $1 (xclock) $0
+...
+-------------------------------------------------------------------------------
+
+More complex example (three FvwmAuto's are running):
+
+-------------------------------------------------------------------------------
+DestroyFunc RestoreIconified
+AddToFunc   RestoreIconified
++ I Current (Iconic) Iconify false
+
+DestroyFunc RegisterFocus
+AddToFunc   RegisterFocus
++ I Exec date +"%T $n focused" >>/tmp/focus-stats.txt
+
+DestroyFunc RegisterUnfocus
+AddToFunc   RegisterUnfocus
++ I Exec date +"%T $n unfocused" >>/tmp/focus-stats.txt
+
+KillModule FvwmAuto
+Module FvwmAuto 250 Raise Nop
+Module FvwmAuto 800 RestoreIconified Nop
+Module FvwmAuto   0 RegisterFocus RegisterUnfocus
+-------------------------------------------------------------------------------
+
+NOTES
+-----
+
+There is a special Raise/Lower support in FvwmAuto. It was added to
+improve Raise/Lower callbacks, since most of FvwmAuto usages is auto-
+raising or auto-lowering. This improvement includes locking on
+M_RAISE_WINDOW and M_LOWER_WINDOW packets and not raising/lowering
+explicitly raised windows.  The special Raise/Lower support is enabled
+only when either EnterCommand or LeaveCommand contain substring "Raise"
+or "Lower". You can use this fact to enable/disable any special support
+by renaming these commands, if FvwmAuto does not automatically do want
+you expect it to do.
+
+Using FvwmAuto in conjunction with EdgeCommand can be even more
+powerful. There is a short example in the fvwm man page.
+
+AUTHOR
+------
+
+FvwmAuto just appeared one day, nobody knows how.
+FvwmAuto was simply rewritten 09/96, nobody knows by whom.

modules/FvwmAuto/Makefile.am

@@ -2,6 +2,8 @@
 
 moduledir = @FVWM_MODULEDIR@
 module_PROGRAMS = FvwmAuto
+FvwmAuto.1:
+	$(ASCIIDOCTOR) -b manpage FvwmAuto.adoc -o FvwmAuto.1
 man_MANS = FvwmAuto.1
 EXTRA_DIST = $(man_MANS)