doc/fvwm/options.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
   3   "../docbook-xml/docbookx.dtd"
   4 [
   5 <!ENTITY % myents SYSTEM "../fvwm.ent" >
   6 %myents;
   7 ]>
   8
   9 <!-- $Id: options.xml,v 1.5 2007/08/19 17:01:21 griph Exp $ -->
  10
  11 <section id='Options'>
  12 <title>Options</title>
  13
  14 <para>These are the command line options that are recognized by fvwm:</para>
  15 <variablelist remap='TP'>
  16   <varlistentry>
  17   <term>
  18     <option>-i</option> | <option>--clientid</option>
  19     <replaceable>id</replaceable>
  20   </term>
  21   <listitem>
  22 <para>
  23 This option is used when fvwm is started by a session
  24 manager. Should not be used by a user.</para>
  25   </listitem>
  26   </varlistentry>
  27   <varlistentry>
  28   <term>
  29     <option>-c</option> | <option>--cmd</option>
  30     <replaceable>config-command</replaceable>
  31   </term>
  32   <listitem>
  33 <para>
  34 Causes fvwm to use
  35 <replaceable>config-command</replaceable>
  36 instead of
  37 '<fvwmref cmd="Read"/>
  38 <emphasis remap='I'>config</emphasis>'
  39 (or '<fvwmref cmd="Read"/>
  40 <emphasis remap='I'>.fvwm2rc</emphasis>')
  41 as its initialization command.  (Note that up to 10
  42 <option>-f</option> and <option>-c</option>
  43 parameters can be given, and they are executed in the order
  44 specified.)</para>
  45
  46 <para>Any module started by command line arguments is assumed to be a
  47 module that sends back config commands.  All command line modules
  48 have to quit before fvwm proceeds on to the StartFunction and
  49 setting border decorations and styles.  There is a potential
  50 deadlock if you start a module other than <fvwmref mod="FvwmCpp"/>/<fvwmref mod="FvwmM4"/>/<fvwmref mod="FvwmPerl"/>
  51 but there is a timeout so fvwm eventually gets going.</para>
  52
  53 <para>As an example, starting the pager this way hangs fvwm until
  54 the timeout, but the following should work well:</para>
  55
  56 <programlisting>
  57 fvwm -c "<fvwmref cmd="AddToFunc"/> StartFunction I <fvwmref cmd="Module"/> <fvwmref mod="FvwmPager"/>"
  58 </programlisting>
  59
  60   </listitem>
  61   </varlistentry>
  62   <varlistentry>
  63   <term>
  64     <option>-d</option> | <option>--display</option>
  65     <replaceable>displayname</replaceable>
  66   </term>
  67   <listitem>
  68 <para>
  69 Manage the display called
  70 <replaceable>displayname</replaceable>
  71 instead of the name obtained from the environment variable
  72 <envar>$DISPLAY</envar>.</para>
  73   </listitem>
  74   </varlistentry>
  75   <varlistentry>
  76   <term>
  77     <option>-D</option> | <option>--debug</option>
  78   </term>
  79   <listitem>
  80 <para>Puts X transactions in synchronous mode, which dramatically slows
  81 things down, but guarantees that fvwm's internal error messages
  82 are correct. Also causes fvwm to output debug messages while
  83 running.</para>
  84   </listitem>
  85   </varlistentry>
  86   <varlistentry>
  87   <term>
  88     <option>-f</option>
  89     <replaceable>config-file</replaceable>
  90   </term>
  91   <listitem>
  92 <para>Causes fvwm to read
  93 <replaceable>config-file</replaceable>
  94 instead of
  95 <filename>~/.fvwm/config</filename>
  96 as its initialization file.  This is equivalent to
  97 -c '<fvwmref cmd="Read"/>
  98 <replaceable>config-file</replaceable>'.</para>
  99   </listitem>
 100   </varlistentry>
 101   <varlistentry>
 102   <term><option>-h</option> | <option>--help</option></term>
 103   <listitem>
 104 <para>A short usage description is printed.</para>
 105   </listitem>
 106   </varlistentry>
 107   <varlistentry>
 108   <term><option>-r</option> | <option>--replace</option></term>
 109   <listitem>
 110 <para>Try to take over from a previously running wm.  This does not work
 111 unless the other wm is
 112 <acronym>ICCCM2</acronym>
 113 2.0 compliant.</para>
 114   </listitem>
 115   </varlistentry>
 116   <varlistentry>
 117   <term>
 118     <option>-F</option> | <option>--restore</option>
 119     <replaceable>state-file</replaceable>
 120   </term>
 121   <listitem>
 122 <para>
 123 This option is used when fvwm is started by a session manager.
 124 Should not be used by a user.</para>
 125   </listitem>
 126   </varlistentry>
 127   <varlistentry>
 128   <term>
 129     <option>-s</option> | <option>--single-screen</option>
 130     <optional><replaceable>screen_num</replaceable></optional>
 131   </term>
 132   <listitem>
 133 <para>
 134 On a multi-screen display, run fvwm only on the screen named in
 135 the
 136 <envar>$DISPLAY</envar>
 137 environment variable or provided through the
 138 <option>-d</option>
 139 option. The optional argument
 140 <replaceable>screen_num</replaceable>
 141 should be positive or null and override the screen number.
 142 Normally, fvwm attempts to start up on all screens of a
 143 multi-screen display.</para>
 144   </listitem>
 145   </varlistentry>
 146   <varlistentry>
 147   <term><option>-V</option> | <option>--version</option></term>
 148   <listitem>
 149 <para>Prints the version of fvwm to
 150 <filename>stderr</filename>.
 151 Also prints an information about the compiled in support for
 152 readline, rplay, stroke, xpm, png, svg, <acronym>GNOME</acronym> hints, <acronym>EWMH</acronym> hints,
 153 session management, bidirectional text, multibyte characters,
 154 xinerama and Xft aa font rendering.</para>
 155   </listitem>
 156   </varlistentry>
 157   <varlistentry>
 158   <term>
 159     <option>-C</option> | <option>--visual</option>
 160     <replaceable>visual-class</replaceable>
 161   </term>
 162   <listitem>
 163 <para>
 164 Causes fvwm to use
 165 <replaceable>visual-class</replaceable>
 166 for the window borders and menus.
 167 <replaceable>visual-class</replaceable>
 168 can be "StaticGray", "GrayScale", "StaticColor", "PseudoColor",
 169 "TrueColor" or "DirectColor".</para>
 170   </listitem>
 171   </varlistentry>
 172   <varlistentry>
 173   <term>
 174     <option>-I</option> | <option>--visualid</option>
 175     <replaceable>id</replaceable>
 176   </term>
 177   <listitem>
 178 <para>
 179 Causes fvwm to use
 180 <replaceable>id</replaceable>
 181 as the visual id for the window borders and menus.
 182 <replaceable>id</replaceable>
 183 can be specified as N for decimal or 0xN for hexadecimal. See man
 184 page of xdpyinfo for a list of supported visuals.</para>
 185   </listitem>
 186   </varlistentry>
 187   <varlistentry>
 188   <term>
 189     <option>-l</option> | <option>--color-limit</option>
 190     <replaceable>limit</replaceable>
 191   </term>
 192   <listitem>
 193
 194 <para>Specifies a <replaceable>limit</replaceable> on the colors
 195 used in image, gradient and possibly simple colors used by
 196 fvwm. In fact, fvwm (and all the modules) uses a palette with at
 197 most <replaceable>limit</replaceable> colors. This option is only
 198 useful with screens that display 256 colors (or less) with a
 199 dynamic visual (PseudoColor, GrayScale or DirectColor). The
 200 default depends on your X server and how you run fvwm. In most
 201 case this default is reasonable. The <option>-l</option> option
 202 should be used only if you encounter problems with colors.  By
 203 default, fvwm tries to detect large pre-allocated palettes. If
 204 such a palette is detected fvwm uses it and a priori the
 205 <option>-l</option> must not be used. Moreover, in this case the
 206 <option>-A</option> and <option>-S</option> options are
 207 forced. Note that XFree-4.2 pre-allocates 244 colors (if you use a
 208 driver with Render support) leaving only a few free colors. This
 209 may lead to some color problems (and nothing can be
 210 done). XFree-4.3 or better pre-allocate only 85 colors.  If no
 211 pre-allocated palette is auto detected the defaults are as
 212 follow:</para>
 213
 214 <variablelist>
 215   <varlistentry>
 216     <term>Display depth 8 (256 colors)</term>
 217     <listitem>
 218       <simplelist>
 219         <member>PseudoColor: 68 (4x4x4 color cube + 4 grey)</member>
 220         <member>GrayScale: 64 regular grey</member>
 221         <member>DirectColor: 32 (3x3x3 color cube + 5 grey)</member>
 222       </simplelist>
 223     </listitem>
 224   </varlistentry>
 225   <varlistentry>
 226     <term>Display depth 4 (16 colors)</term>
 227     <listitem>
 228       <simplelist>
 229         <member>PseudoColor: 10 (2x2x2 color cube + 2 grey)</member>
 230         <member>GrayScale: 8 regular grey</member>
 231         <member>DirectColor: 10 (2x2x2 color cube + 2 grey)</member>
 232       </simplelist>
 233     </listitem>
 234   </varlistentry>
 235 </variablelist>
 236
 237 <para>These defaults may change before version 2.6. Note that if
 238 you use a private color map (i.e., fvwm is started with the
 239 <option>-C</option> or the <option>-I</option> options), then
 240 other defaults are used.</para>
 241
 242 <para>Now what to do if you encounter problems with colors? The first
 243 thing to do is to check if you really cannot run your X server
 244 with depth 15, 16 or better.  Check your X server
 245 documentation. Note that some hardware can support two different
 246 depths on the same screen (typically depth 8 and depth 24). If
 247 depth 8 is the default, you can force fvwm to use the best depth
 248 by using the
 249 <option>-C</option>
 250 option with
 251 <emphasis remap='I'>TrueColor</emphasis>
 252 as argument.  So now we assume that you are forced to run in depth
 253 8 with a dynamic visual because your hardware/driver cannot do
 254 better or because you need to use an application which needs to
 255 run under this mode (e.g., because this application needs
 256 read-write colors). What it should be understand is that you have
 257 only 256 colors and that all the applications which use the
 258 default color map must share these colors. The main problem is
 259 that there are applications which use a lot or even all the
 260 colors.  If you use such application you may have no more free
 261 colors and some applications (which used only a few colors) may
 262 fail to start or are unusable. There are three things that can be
 263 done (and fvwm does not really play a particular role, all
 264 applications are concerned). The first is to run the applications
 265 which waste your (default) color map with a private color map. For
 266 example, run netscape with the -install option, run <acronym>KDE</acronym>
 267 or <acronym>QT</acronym>
 268 applications with the --cmap option, use the
 269 <option>-C</option>
 270 option for fvwm. The disadvantage of this method is that it is
 271 visually disturbing (see the
 272 <fvwmref cmd="ColormapFocus"/>
 273 command for a better control of the color maps switching). The
 274 second method is to limit the number of colors that the
 275 applications use. Again, some applications have options to
 276 specify a given color limit. With fvwm you may try various values,
 277 61 (a special "visual" palette), 56 (a 4x4x3 color cube plus 6
 278 grey), 29 (a 3x3x3 color cube plus 2 grey), 10 or 9. Also, you may
 279 use the
 280 <option>-L</option>
 281 option.  However, limiting the number of colors is not the
 282 definitive solution. The definitive solution is to try cause
 283 applications which use a lot of colors use the same colors. This
 284 is a difficult task as there are no formal standards for this
 285 goal. However, some toolkits as <acronym>QT</acronym> and
 286 <acronym>GTK</acronym> use color cubes as
 287 palettes. So, the idea is to configure your applications/toolkits
 288 to all use the same color cube. Moreover, you can use the colors
 289 in this color cube in your X resources configuration files and/or
 290 as arguments to colors options.
 291 Fvwm can use any color cube of the form RxGxB with 2 &lt;= R &lt;= 6, R
 292 = G, R-1 =&lt; B &lt;= R and B &gt;= 2. To get an RxGxB color cube give an
 293 argument to
 294 <option>-l</option>
 295 an integer c &gt;= R*G*B and &lt; (R+1)*(G+1)*B if B=R and &lt; R*G*(B+1)
 296 if B &lt; R (and different from 61). If c &gt; R*G*B, then some grey may
 297 be added to the color cube. You can use the
 298 <fvwmref cmd="PrintInfo"/>
 299 <emphasis remap='I'>Colors</emphasis>
 300 <optional><emphasis remap='I'>1</emphasis></optional>
 301 command to get information on your fvwm colors setting. In
 302 particular, this command prints the palette used by fvwm in rgb
 303 format (the last integer gives the number of times fvwm has
 304 allocated the colors).</para>
 305   </listitem>
 306   </varlistentry>
 307   <varlistentry>
 308   <term><option>-L</option> | <option>--strict-color-limit</option></term>
 309   <listitem>
 310 <para>If the screen displays 256 colors (or less) and has a dynamic visual,
 311 causes fvwm to use its palette for all the colors. By default, the
 312 palette is used only for images and gradients.</para>
 313   </listitem>
 314   </varlistentry>
 315   <varlistentry>
 316   <term><option>-P</option> | <option>--visual-palette</option></term>
 317   <listitem>
 318 <para>If the screen displays 256 colors (or less) and has a dynamic
 319 visual, this option causes fvwm to use a palette designed for
 320 limiting the "visual" color distance between the points of the
 321 palette. Moreover, for better color sharing, if possible colors
 322 with a name in the X rgb data base are used for defining the
 323 colors (with the hope that applications and images prefer to
 324 use named colors). If the
 325 <option>-l</option>
 326 option is not used this palette has 61 colors. This palette is
 327 also automatically selected if  61 or 9 is used as argument to the
 328 <option>-l</option>
 329 option.</para>
 330   </listitem>
 331   </varlistentry>
 332   <varlistentry>
 333   <term><option>-A</option> | <option>--allocate-palette</option></term>
 334   <listitem>
 335 <para>If the screen displays 256 colors (or less) and has a dynamic
 336 visual this option causes fvwm to allocate all the colors of its
 337 palette at start up for reserving these colors for future
 338 use. This option forces the
 339 <option>-static-palette</option>
 340 option. By default, fvwm allocates (reserves) a color in its palette
 341 only if it needs this color.</para>
 342   </listitem>
 343   </varlistentry>
 344   <varlistentry>
 345   <term><option>-S</option> | <option>--static-palette</option></term>
 346   <listitem>
 347 <para>If the screen displays 256 colors (or less) and has a dynamic
 348 visual this option causes fvwm to never free the colors in its
 349 palette. By default, when fvwm does not need a color any more it
 350 frees this color so that a new color can be used. This option may
 351 speed up image loading and save a few bits of memory.</para>
 352   </listitem>
 353   </varlistentry>
 354   <varlistentry>
 355   <term><option>-blackout</option></term>
 356   <listitem>
 357 <para>This option is provided for backward compatibility only.  Blacking
 358 out the screen during startup is not necessary (and doesn't work)
 359 anymore. This option will be removed in the future.</para>
 360   </listitem>
 361   </varlistentry>
 362   <varlistentry>
 363   <term><option>--debug-stack-ring</option></term>
 364   <listitem>
 365 <para>Enables stack ring debugging.  This option is only intended for
 366 internal debugging and should only be used by developers.</para>
 367
 368   </listitem>
 369   </varlistentry>
 370 </variablelist>
 371 </section>