Misc #215: Reformat usage text & update docs

- Reformat usage text by adding a blank line between descriptions of
   two switches. (#215)

 - Update documentation for a bit. Correct some wrong statements and
   clarify some others.

man/compton.1.asciidoc

@@ -2,7 +2,7 @@ compton(1)
 ==========
 :doctype:     manpage
 :man source:  compton
-:man version: nightly-20140419
+:man version: nightly-20141124
 :man manual:  LOCAL USER COMMANDS
 
 NAME
@@ -78,7 +78,7 @@ OPTIONS
 	Don't draw shadows on drag-and-drop windows.
 
 *-b*, *--daemon*::
-	Daemonize process. Fork to background after initialization.
+	Daemonize process. Fork to background after initialization. Causes issues with certain (badly-written) drivers.
 
 *-S*::
 	Enable synchronous X operation (for debugging).
@@ -87,7 +87,7 @@ OPTIONS
 	Show all X errors (for debugging).
 
 *--config* 'PATH'::
-	Look for configuration file at the path. See *CONFIGURATION FILES* section below for where compton looks for a configuration file by default.
+	Look for configuration file at the path. See *CONFIGURATION FILES* section below for where compton looks for a configuration file by default. Use `/dev/null` to avoid loading configuration file.
 
 *--write-pid-path* 'PATH'::
 	Write process ID to a file.
@@ -123,7 +123,7 @@ OPTIONS
 	Do not fade destroyed ARGB windows with WM frame. Workaround of bugs in Openbox, Fluxbox, etc.
 
 *--shadow-ignore-shaped*::
-	Do not paint shadows on shaped windows. Note shaped windows here means windows setting its shape through X Shape extension. Those using ARGB background is beyond our control.
+	Do not paint shadows on shaped windows. Note shaped windows here means windows setting its shape through X Shape extension. Those using ARGB background is beyond our control. Deprecated, use `--shadow-exclude 'bounding_shaped'` or `--shadow-exclude 'bounding_shaped && !rounded_corners'` instead.
 
 *--detect-rounded-corners*::
 	Try to detect windows with rounded corners and don't consider them shaped windows. The accuracy is not very high, unfortunately.
@@ -139,10 +139,10 @@ OPTIONS
 +
 --
 * 'none': No VSync
-* 'drm': VSync with 'DRM_IOCTL_WAIT_VBLANK'. May only work on some drivers.
+* 'drm': VSync with 'DRM_IOCTL_WAIT_VBLANK'. May only work on some (DRI-based) drivers.
 * 'opengl': Try to VSync with 'SGI_video_sync' OpenGL extension. Only work on some drivers.
 * 'opengl-oml': Try to VSync with 'OML_sync_control' OpenGL extension. Only work on some drivers.
-* 'opengl-swc': Try to VSync with 'SGI_swap_control' OpenGL extension. Only work on some drivers. Works only with GLX backend. Known to be most effective on many drivers. Does not actually control paint timing, only buffer swap is affected, so it doesn't have the effect of *--sw-opti* unlike other methods. Experimental.
+* 'opengl-swc': Try to VSync with 'SGI_swap_control' OpenGL extension. Only work on some drivers. Works only with GLX backend. Known to be most effective on many drivers. Does not guarantee to control paint timing.
 * 'opengl-mswc': Try to VSync with 'MESA_swap_control' OpenGL extension. Basically the same as 'opengl-swc' above, except the extension we use.
 
 (Note some VSync methods may not be enabled at compile time.)

src/compton.c

@@ -4470,93 +4470,133 @@ usage(int ret) {
     "\n"
     "-d display\n"
     "  Which display should be managed.\n"
+    "\n"
     "-r radius\n"
     "  The blur radius for shadows. (default 12)\n"
+    "\n"
     "-o opacity\n"
     "  The translucency for shadows. (default .75)\n"
+    "\n"
     "-l left-offset\n"
     "  The left offset for shadows. (default -15)\n"
+    "\n"
     "-t top-offset\n"
     "  The top offset for shadows. (default -15)\n"
+    "\n"
     "-I fade-in-step\n"
     "  Opacity change between steps while fading in. (default 0.028)\n"
+    "\n"
     "-O fade-out-step\n"
     "  Opacity change between steps while fading out. (default 0.03)\n"
+    "\n"
     "-D fade-delta-time\n"
     "  The time between steps in a fade in milliseconds. (default 10)\n"
+    "\n"
     "-m opacity\n"
     "  The opacity for menus. (default 1.0)\n"
+    "\n"
     "-c\n"
     "  Enabled client-side shadows on windows.\n"
+    "\n"
     "-C\n"
     "  Avoid drawing shadows on dock/panel windows.\n"
+    "\n"
     "-z\n"
-    "  Zero the part of the shadow's mask behind the window (experimental).\n"
+    "  Zero the part of the shadow's mask behind the window.\n"
+    "\n"
     "-f\n"
     "  Fade windows in/out when opening/closing and when opacity\n"
     "  changes, unless --no-fading-openclose is used.\n"
+    "\n"
     "-F\n"
-    "  Equals -f. Deprecated.\n"
+    "  Equals to -f. Deprecated.\n"
+    "\n"
     "-i opacity\n"
     "  Opacity of inactive windows. (0.1 - 1.0)\n"
+    "\n"
     "-e opacity\n"
     "  Opacity of window titlebars and borders. (0.1 - 1.0)\n"
+    "\n"
     "-G\n"
     "  Don't draw shadows on DND windows\n"
+    "\n"
     "-b\n"
     "  Daemonize process.\n"
+    "\n"
     "-S\n"
     "  Enable synchronous operation (for debugging).\n"
+    "\n"
     "--show-all-xerrors\n"
     "  Show all X errors (for debugging).\n"
+    "\n"
     "--config path\n"
-    "  Look for configuration file at the path.\n"
+    "  Look for configuration file at the path. Use /dev/null to avoid\n"
+    "  loading configuration file.\n"
+    "\n"
     "--write-pid-path path\n"
     "  Write process ID to a file.\n"
+    "\n"
     "--shadow-red value\n"
     "  Red color value of shadow (0.0 - 1.0, defaults to 0).\n"
+    "\n"
     "--shadow-green value\n"
     "  Green color value of shadow (0.0 - 1.0, defaults to 0).\n"
+    "\n"
     "--shadow-blue value\n"
     "  Blue color value of shadow (0.0 - 1.0, defaults to 0).\n"
+    "\n"
     "--inactive-opacity-override\n"
     "  Inactive opacity set by -i overrides value of _NET_WM_OPACITY.\n"
+    "\n"
     "--inactive-dim value\n"
     "  Dim inactive windows. (0.0 - 1.0, defaults to 0)\n"
+    "\n"
     "--active-opacity opacity\n"
     "  Default opacity for active windows. (0.0 - 1.0)\n"
+    "\n"
     "--mark-wmwin-focused\n"
     "  Try to detect WM windows and mark them as active.\n"
+    "\n"
     "--shadow-exclude condition\n"
     "  Exclude conditions for shadows.\n"
+    "\n"
     "--fade-exclude condition\n"
     "  Exclude conditions for fading.\n"
+    "\n"
     "--mark-ovredir-focused\n"
     "  Mark windows that have no WM frame as active.\n"
+    "\n"
     "--no-fading-openclose\n"
     "  Do not fade on window open/close.\n"
+    "\n"
     "--no-fading-destroyed-argb\n"
     "  Do not fade destroyed ARGB windows with WM frame. Workaround of bugs\n"
     "  in Openbox, Fluxbox, etc.\n"
+    "\n"
     "--shadow-ignore-shaped\n"
     "  Do not paint shadows on shaped windows. (Deprecated, use\n"
     "  --shadow-exclude \'bounding_shaped\' or\n"
     "  --shadow-exclude \'bounding_shaped && !rounded_corners\' instead.)\n"
+    "\n"
     "--detect-rounded-corners\n"
     "  Try to detect windows with rounded corners and don't consider\n"
     "  them shaped windows. Affects --shadow-ignore-shaped,\n"
     "  --unredir-if-possible, and possibly others. You need to turn this\n"
     "  on manually if you want to match against rounded_corners in\n"
     "  conditions.\n"
+    "\n"
     "--detect-client-opacity\n"
     "  Detect _NET_WM_OPACITY on client windows, useful for window\n"
     "  managers not passing _NET_WM_OPACITY of client windows to frame\n"
     "  windows.\n"
+    "\n"
     "--refresh-rate val\n"
     "  Specify refresh rate of the screen. If not specified or 0, compton\n"
     "  will try detecting this with X RandR extension.\n"
+    "\n"
     "--vsync vsync-method\n"
-    "  Set VSync method. There are up to 4 VSync methods currently available.\n"
+    "  Set VSync method. There are (up to) 5 VSync methods currently\n"
+    "  available:\n"
     "    none = No VSync\n"
 #undef WARNING
 #ifndef CONFIG_VSYNC_DRM
@@ -4565,7 +4605,7 @@ usage(int ret) {
 #define WARNING
 #endif
     "    drm = VSync with DRM_IOCTL_WAIT_VBLANK. May only work on some\n"
-    "      drivers." WARNING "\n"
+    "      (DRI-based) drivers." WARNING "\n"
 #undef WARNING
 #ifndef CONFIG_VSYNC_OPENGL
 #define WARNING WARNING_DISABLED
@@ -4575,67 +4615,82 @@ usage(int ret) {
     "    opengl = Try to VSync with SGI_video_sync OpenGL extension. Only\n"
     "      work on some drivers." WARNING"\n"
     "    opengl-oml = Try to VSync with OML_sync_control OpenGL extension.\n"
-    "      Only work on some drivers. Experimental." WARNING"\n"
+    "      Only work on some drivers." WARNING"\n"
     "    opengl-swc = Try to VSync with SGI_swap_control OpenGL extension.\n"
-    "      Only work on some drivers. Works only with GLX backend.\n"
+    "      Only work on some drivers. Works only with GLX backend." WARNING "\n"
-    "      Does not actually control paint timing, only buffer swap is\n"
-    "      affected, so it doesn't have the effect of --sw-opti unlike\n"
-    "      other methods." WARNING "\n"
     "    opengl-mswc = Try to VSync with MESA_swap_control OpenGL\n"
     "      extension. Basically the same as opengl-swc above, except the\n"
     "      extension we use." WARNING "\n"
+    "\n"
     "--vsync-aggressive\n"
     "  Attempt to send painting request before VBlank and do XFlush()\n"
     "  during VBlank. This switch may be lifted out at any moment.\n"
+    "\n"
     "--alpha-step val\n"
     "  X Render backend: Step for pregenerating alpha pictures. \n"
     "  0.01 - 1.0. Defaults to 0.03.\n"
+    "\n"
     "--dbe\n"
     "  Enable DBE painting mode, intended to use with VSync to\n"
     "  (hopefully) eliminate tearing.\n"
+    "\n"
     "--paint-on-overlay\n"
     "  Painting on X Composite overlay window.\n"
+    "\n"
     "--sw-opti\n"
     "  Limit compton to repaint at most once every 1 / refresh_rate\n"
     "  second to boost performance.\n"
+    "\n"
     "--use-ewmh-active-win\n"
     "  Use _NET_WM_ACTIVE_WINDOW on the root window to determine which\n"
     "  window is focused instead of using FocusIn/Out events.\n"
+    "\n"
     "--respect-prop-shadow\n"
     "  Respect _COMPTON_SHADOW. This a prototype-level feature, which\n"
     "  you must not rely on.\n"
+    "\n"
     "--unredir-if-possible\n"
     "  Unredirect all windows if a full-screen opaque window is\n"
     "  detected, to maximize performance for full-screen windows.\n"
+    "\n"
     "--unredir-if-possible-delay ms\n"
     "  Delay before unredirecting the window, in milliseconds.\n"
     "  Defaults to 0.\n"
+    "\n"
     "--unredir-if-possible-exclude condition\n"
     "  Conditions of windows that shouldn't be considered full-screen\n"
     "  for unredirecting screen.\n"
+    "\n"
     "--focus-exclude condition\n"
     "  Specify a list of conditions of windows that should always be\n"
     "  considered focused.\n"
+    "\n"
     "--inactive-dim-fixed\n"
     "  Use fixed inactive dim value.\n"
+    "\n"
     "--detect-transient\n"
     "  Use WM_TRANSIENT_FOR to group windows, and consider windows in\n"
     "  the same group focused at the same time.\n"
+    "\n"
     "--detect-client-leader\n"
     "  Use WM_CLIENT_LEADER to group windows, and consider windows in\n"
     "  the same group focused at the same time. WM_TRANSIENT_FOR has\n"
     "  higher priority if --detect-transient is enabled, too.\n"
+    "\n"
     "--blur-background\n"
     "  Blur background of semi-transparent / ARGB windows. Bad in\n"
     "  performance. The switch name may change without prior\n"
     "  notifications.\n"
+    "\n"
     "--blur-background-frame\n"
     "  Blur background of windows when the window frame is not opaque.\n"
     "  Implies --blur-background. Bad in performance. The switch name\n"
     "  may change.\n"
+    "\n"
     "--blur-background-fixed\n"
     "  Use fixed blur strength instead of adjusting according to window\n"
     "  opacity.\n"
+    "\n"
     "--blur-kern matrix\n"
     "  Specify the blur convolution kernel, with the following format:\n"
     "    WIDTH,HEIGHT,ELE1,ELE2,ELE3,ELE4,ELE5...\n"
@@ -4649,22 +4704,27 @@ usage(int ret) {
     "  May also be one the predefined kernels: 3x3box (default), 5x5box,\n"
     "  7x7box, 3x3gaussian, 5x5gaussian, 7x7gaussian, 9x9gaussian,\n"
     "  11x11gaussian.\n"
+    "\n"
     "--blur-background-exclude condition\n"
     "  Exclude conditions for background blur.\n"
+    "\n"
     "--resize-damage integer\n"
     "  Resize damaged region by a specific number of pixels. A positive\n"
     "  value enlarges it while a negative one shrinks it. Useful for\n"
     "  fixing the line corruption issues of blur. May or may not\n"
     "  work with --glx-no-stencil. Shrinking doesn't function correctly.\n"
+    "\n"
     "--invert-color-include condition\n"
     "  Specify a list of conditions of windows that should be painted with\n"
     "  inverted color. Resource-hogging, and is not well tested.\n"
+    "\n"
     "--opacity-rule opacity:condition\n"
     "  Specify a list of opacity rules, in the format \"PERCENT:PATTERN\",\n"
     "  like \'50:name *= \"Firefox\"'. compton-trans is recommended over\n"
     "  this. Note we do not distinguish 100% and unset, and we don't make\n"
     "  any guarantee about possible conflicts with other programs that set\n"
     "  _NET_WM_WINDOW_OPACITY on frame or client windows.\n"
+    "\n"
     "--shadow-exclude-reg geometry\n"
     "  Specify a X geometry that describes the region in which shadow\n"
     "  should not be painted in, such as a dock window region.\n"
@@ -4676,32 +4736,39 @@ usage(int ret) {
 #else
 #define WARNING
 #endif
+    "\n"
     "--xinerama-shadow-crop\n"
     "  Crop shadow of a window fully on a particular Xinerama screen to the\n"
     "  screen." WARNING "\n"
+    "\n"
     "--backend backend\n"
     "  Choose backend. Possible choices are xrender, glx, and\n"
     "  xr_glx_hybrid" WARNING ".\n"
+    "\n"
     "--glx-no-stencil\n"
     "  GLX backend: Avoid using stencil buffer. Might cause issues\n"
     "  when rendering transparent content. My tests show a 15% performance\n"
     "  boost.\n"
+    "\n"
     "--glx-copy-from-front\n"
     "  GLX backend: Copy unmodified regions from front buffer instead of\n"
     "  redrawing them all. My tests with nvidia-drivers show a 5% decrease\n"
     "  in performance when the whole screen is modified, but a 30% increase\n"
     "  when only 1/4 is. My tests on nouveau show terrible slowdown. Could\n"
     "  work with --glx-swap-method but not --glx-use-copysubbuffermesa.\n"
+    "\n"
     "--glx-use-copysubbuffermesa\n"
     "  GLX backend: Use MESA_copy_sub_buffer to do partial screen update.\n"
     "  My tests on nouveau shows a 200% performance boost when only 1/4 of\n"
     "  the screen is updated. May break VSync and is not available on some\n"
     "  drivers. Overrides --glx-copy-from-front.\n"
+    "\n"
     "--glx-no-rebind-pixmap\n"
     "  GLX backend: Avoid rebinding pixmap on window damage. Probably\n"
     "  could improve performance on rapid window content changes, but is\n"
     "  known to break things on some drivers (LLVMpipe, xf86-video-intel,\n"
     "  etc.).\n"
+    "\n"
     "--glx-swap-method undefined/copy/exchange/3/4/5/6/buffer-age\n"
     "  GLX backend: GLX buffer swap method we assume. Could be\n"
     "  undefined (0), copy (1), exchange (2), 3-6, or buffer-age (-1).\n"
@@ -4710,9 +4777,11 @@ usage(int ret) {
     "  but safer (6 is still faster than 0). -1 means auto-detect using\n"
     "  GLX_EXT_buffer_age, supported by some drivers. Useless with\n"
     "  --glx-use-copysubbuffermesa.\n"
+    "\n"
     "--glx-use-gpushader4\n"
     "  GLX backend: Use GL_EXT_gpu_shader4 for some optimization on blur\n"
     "  GLSL code. My tests on GTX 670 show no noticeable effect.\n"
+    "\n"
     "--xrender-sync\n"
     "  Attempt to synchronize client applications' draw calls with XSync(),\n"
     "  used on GLX backend to ensure up-to-date window content is painted.\n"
@@ -4722,6 +4791,7 @@ usage(int ret) {
 #else
 #define WARNING
 #endif
+    "\n"
     "--xrender-sync-fence\n"
     "  Additionally use X Sync fence to sync clients' draw calls. Needed\n"
     "  on nvidia-drivers with GLX backend for some users." WARNING "\n"
@@ -4731,17 +4801,22 @@ usage(int ret) {
 #else
 #define WARNING
 #endif
+    "\n"
     "--glx-fshader-win shader\n"
     "  GLX backend: Use specified GLSL fragment shader for rendering window\n"
     "  contents.\n"
+    "\n"
     "--force-win-blend\n"
     "  Force all windows to be painted with blending. Useful if you have a\n"
     "  --glx-fshader-win that could turn opaque pixels transparent.\n"
+    "\n"
     "--dbus\n"
     "  Enable remote control via D-Bus. See the D-BUS API section in the\n"
     "  man page for more details." WARNING "\n"
+    "\n"
     "--benchmark cycles\n"
     "  Benchmark mode. Repeatedly paint until reaching the specified cycles.\n"
+    "\n"
     "--benchmark-wid window-id\n"
     "  Specify window ID to repaint in benchmark mode. If omitted or is 0,\n"
     "  the whole screen is repainted.\n"