home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 22 gnu / 22-gnu.zip / gwm18a.zip / doc / usage.tex (.txt) < prev    next >
LaTeX Document  |  1995-07-03  |  8KB  |  146 lines
  1. \chapter{Usage}
  2. {\tt gwm [-1DstqmFiawWIPr?] [-x screens]  [-f profile] [-p path] [-d display]}
  3. \section{Options}
  4. The following command-line options\footnote{The options follow the
  5. GETOPTS(3) conventions: they can be in any order, a space is optional between
  6. an option and its argument; they can be combined (as in {\tt -Dmt}), but all
  7. options must appear {\bf before} any argument, which is the managed display
  8. for {\tt gwm}.} are supported:
  9. \begin{description}
  10. \item[-f filename] Names an alternate file as a {\GWM} startup file.
  11. Default is {\bf .gwmrc.gwm} (note that the \verb".gwm" extension is
  12. optional, as for any {\WOOL} file).\sloppy 
  13. For instance, to use the {\sc Motif} emulation package, type
  14. \verb"gwm -f mwm".
  15. \item[-p~path] \label{GWMPATH}Gives the path to be searched for {\WOOL} or bitmap
  16. files when loaded, including the startup file. Overrides the setting by the
  17. environment variable {\bf GWMPATH}.  Defaults to \linebreak
  18. \verb".:$HOME:$HOME/gwm:GWMDIR", where {\tt GWMDIR} is the local directory
  19. where {\GWM} is installed (normally, {\tt /usr/local/lib/X11/gwm}).
  20. You can append or prepend a path to the current path by preceding the path
  21. given as argument to the \verb"-p" option by \verb"+" (for appending) or
  22. \verb"-" (for prepending). For instance, if you want to search the directory
  23. \verb"/usr/local/gwm" before the standard ones (including your homedir),
  24. just say: \verb"-p -/usr/local/gwm".
  25. \item[-d display] Specifies the name of the display whose windows must be
  26. managed, such as \verb"unix:0". The \verb"-d" is optional, you can type
  27. \verb"gwm unix:0".
  28. \item[-x screens] Do not manage the screens given in the comma-separated
  29. list of numbers, as in: {\tt -x 2,5,3}. Normally, {\GWM} manages {\bf all}
  30. the screens of the given display.
  31. \item[-1] Manages only the given screen, e.g. \verb"gwm -1 foo:0.2" manages
  32. only the third screen of the display number \verb"0" on the \verb"foo"
  33. machine. Same as defining the GWM\_MONOSCREEN shell variable.
  34. \item[-I] Continues reading interactively {\WOOL} expressions from the
  35. standard input and prints their result. Useful for testing interactively code.
  36. \item[-P] When used with -I, makes {\GWM} issue a simple prompt displaying the
  37. current parenthese level.
  38. \item[-D] Enables debugging mode for {\WOOL} files. In this version the only
  39. effect of debug mode is to continue reading a file after a {\WOOL}
  40. error occurred. Default behavior is to abort reading a file after an error.
  41. Thus, if you modified your profile and introduced an error, {\GWM} will
  42. refuse to complete execution, use {\tt gwm -D} to run it anyway.
  43. \item[-s] Synchronize X calls, useful for debugging but slower.
  44. \item[-t] Turns tracing on, as if you had done the call \verb"(trace t)" in
  45. your profile.
  46. \item[-q] (Quiet) Does not print startup banner, and sets the {\WOOL}
  47. \verb"gwm-quiet" variable to 1.
  48. \item[-m] Maps all toplevel windows already on screen. Useful after
  49. unmapping some windows by accident.
  50. \item[-F] Does not freeze the server during pop-up menus, move and resize of
  51. the windows, which is the default behavior.
  52. \item[-i] Disables the setting of input focus by {\GWM} (\verb"set-focus"
  53. has no effects, except \verb"(set-focus ())", which resets the focus to
  54. PointerRoot) on a window, keypresses go to the window under the cursor. Very
  55. useful to debug profiles with only one screen.
  56. \item[-a] Asynchronously handle moves and resizes, do not cancel a
  57. move or a resize operation if the user released the button before the grid
  58. appeared, which is the default behavior.
  59. \item[-k process-id]
  60. Kills a process once initialization is done. Takes a process id as an
  61. argument. When gwm has finished initializing, it sends a signal (SIGALRM
  62. by default, but this can be changed by -K, see below) to the given process. 
  63. So, if you do the following lines:
  64. \begin{verbatim} 
  65. sleep 15 & pid=$!
  66. gwm -k $pid &
  67. wait $pid
  68. \end{verbatim}
  69. then your init shell script will pause until gwm has finished initializing.
  70. \item[-K signal]
  71. sets the signal to use (number) instead of SIGALRM for the -k option above.
  72. \item[-r]
  73. Normally, when {\GWM} starts and sees that another window manager has still the
  74. control of the display, gwm aborts with a warning message. Specifying -r makes
  75. it retrying till it can get control.
  76. \item[-w window-id]
  77. Makes {\GWM} decorate only one window, given by its ID, a decimal number
  78. \item[-W]
  79. Makes {\GWM} decorate all windows on screen, even if another window manager 
  80. is already in charge.
  81. \item[-?] This, or any invalid option lists the available options and shows the
  82. default path defined at compile time by your local installer.
  83. \end{description}
  84. \section{Shell variables}
  85. {\GWM} can make use of the following shell variables:
  86. \begin{description}
  87. \item[GWMPATH] \sloppy for the path to search for files. If unset, defaults to
  88. \verb".:$HOME:$HOME/gwm:GWMDIR", where {\tt GWMDIR} is the local directory
  89. in which are installed all the standard {\GWM} files. (Normally {\tt
  90. /usr/local/lib/X11/gwm}). Overridden by the \verb"-p" command line option.
  91. \item[GWMPROFILE] for the name of the profile file. Defaults to
  92. \verb".gwmrc.gwm". Overridden by the \verb"-f" command line option.
  93. \item[DISPLAY] for the name of the X11 display to use, such as
  94. \verb"unix:0.0". Overridden by the \verb"-d" command line option.
  95. \item[GWM\_MONOSCREEN] if set will make {\GWM} manage only the given screen.
  96. \item[NO\_KOALA\_SPY   NO\_GWM\_LOG] By default, gwm sends silently one udp
  97.  packet when started to the author with the hostname of the machine as
  98. contnts, to maintain some rough statistics of use. If you dont want this to
  99. happen, you can set either of these two variables to anything, or recompile
  100. with either of these preprocesssor symbols defined.
  101. \end{description}
  102. \section{Files}
  103. {\GWM} needs at least one file for its startup, \verb".gwmrc.gwm" which must
  104. be in {\GWM}'s path. New users do not need one, since a default profile should
  105. already be present in the default path. The standard profile (see
  106. \ref{standard-profile}, p~\pageref{standard-profile}) makes use of the
  107. \verb".profile.gwm" file in the home directory.
  108. The value of the default path can be printed by calling {\GWM} with the
  109. \verb"-?" command line option.
  110. The standard extensions used for {\GWM} file names are:
  111. \begin{description}
  112. \item[{\tt .gwm}] for {\WOOL} files.
  113. \item[{\tt .xbm}] for {\bf X}11 {\bf B}it{\bf M}ap files, such as those
  114. created with BITMAP(1).
  115. \item[{\tt .xpm}] for {\bf X}11 {\bf P}ix{\bf M}ap files, which is an ASCII
  116. portable format for distributing color images (see the \verb"pixmap-load"
  117. function, p~\pageref{pixmap-load}).
  118. \end{description}
  119. \section{Description}
  120. The {\GWM} command is a window manager client application of the X11 window
  121. server specified in the {\tt display} argument (or the  {\tt DISPLAY} shell
  122. variable if no argument is given), extensible via a built-in {\it lisp\/}
  123. interpreter, {\WOOL} (Window Object Oriented Lisp) used to build {\bf Wobs}
  124. (Window OBjects) which are used to decorate the windows of the other X11
  125. applications running on the display. {\GWM}
  126. tries to enforce the ICCCM conventions to communicate between X11 clients
  127. and thus should be compatible with any well-behaved X11 application.
  128. On startup, {\GWM} interprets its profile to build wobs describing how to
  129. decorate user windows, which we will call {\bf Clients}.  Then it creates
  130. {\bf Windows} around each client windows on the screens attached to the
  131. managed display. A Window is made of 4 (optional) {\bf Bars} on the 4 sides
  132. of the window.  Each of these bars is made of a variable number of {\bf
  133. Plugs}, the most primitive wobs.  {\bf Menus} can then be made with a list
  134. of bars. To each of these objects is associated a {\bf fsm} ({\bf F}inite
  135. {\bf S}tate {\bf M}achine) describing their behavior in terms of {\WOOL}
  136. code triggered by X or {\WOOL} events.
  137. When {\GWM} wants to decorate a window, it calls the user-defined {\WOOL}
  138. function \verb"describe-window" which must return a list of two window
  139. descriptions (one for the window itself, and one for its icon) made by the
  140. \verb"window-make" {\WOOL} primitive describing the window. To build these
  141. descriptions the user can query the client window for any X11 properties and
  142. use the X11 Resource Manager to decide how to decorate it.
  143. The screens must also be described by such a description that {\GWM} will find
  144. by calling the user-defined {\WOOL} function \verb"describe-screen" for each
  145. managed screen.
  146.