Update documentation to include all RandR 1.2 options.randr-1.2

Also, require libXrandr version 1.2.0.0 or better.

3 files changed, 117 insertions, 75 deletions

diff --git a/configure.ac b/configure.ac
index f0a39f8..72d6f53 100644
--- a/configure.ac
+++ b/configure.ac
@@ -32,7 +32,7 @@ AC_PROG_CC
 AC_PROG_INSTALL
 
 # Checks for pkg-config packages
-PKG_CHECK_MODULES(XRANDR, xrandr xrender x11)
+PKG_CHECK_MODULES(XRANDR, xrandr >= 1.2.0.0 xrender x11)
 AC_SUBST(XRANDR_CFLAGS)
 AC_SUBST(XRANDR_LIBS)
 
diff --git a/xrandr.c b/xrandr.c
index 0866a57..043e08f 100644
--- a/xrandr.c
+++ b/xrandr.c
@@ -100,19 +100,19 @@ usage(void)
     fprintf(stderr, "  --extend\n");
 #endif
     fprintf(stderr, "  --output <output>\n");
-    fprintf(stderr, "      --crtc <crtc>\n");
+    fprintf(stderr, "      --auto\n");
     fprintf(stderr, "      --mode <mode>\n");
-    fprintf(stderr, "      --rate <rate> or --refresh <rate>\n");
     fprintf(stderr, "      --preferred\n");
     fprintf(stderr, "      --pos <x>x<y>\n");
-    fprintf(stderr, "      --rotate normal,inverted,left,right\n");
+    fprintf(stderr, "      --rate <rate> or --refresh <rate>\n");
     fprintf(stderr, "      --reflect normal,x,y,xy\n");
-    fprintf(stderr, "      --auto\n");
+    fprintf(stderr, "      --rotate normal,inverted,left,right\n");
     fprintf(stderr, "      --left-of <output>\n");
     fprintf(stderr, "      --right-of <output>\n");
     fprintf(stderr, "      --above <output>\n");
     fprintf(stderr, "      --below <output>\n");
     fprintf(stderr, "      --off\n");
+    fprintf(stderr, "      --crtc <crtc>\n");
 #endif
 
     exit(1);
diff --git a/xrandr.man b/xrandr.man
index b1cb430..72bddc4 100644
--- a/xrandr.man
+++ b/xrandr.man
@@ -27,93 +27,135 @@ xrandr \- primitive command line interface to RandR extension
 .SH SYNOPSIS
 .B "xrandr"
 [-help]  [-display \fIdisplay\fP]
-[-o \fIorientation\fP]
 [-q] [-v]
-[-s \fIsize\fP]
-[-x] [-y]
-[--screen \fIsnum\fP]
 [--verbose]
+[--screen \fIsnum\fP]
 .br
+.B RandR version 1.2 options
+.br
+[--prop]
 [--fb <width>x<height>]
+[--fbmm <width>x<height>]
 [--dpi <dpi>]
+.br
+.B Per-output options
+.br
 [--output <output>]
-[--crtc <crtc>]
+[--auto]
 [--mode <mode>]
+[--preferred]
 [--pos <x>x<y>]
+[--rate <rate>]
+[--reflect \fIreflection\fP]
+[--rotate \fIorientation\fP]
+[--left-of <output>\]
+[--right-of <output>\]
+[--above <output>\]
+[--below <output>\]
 [--off]
+[--crtc <crtc>]
+.br
+.B RandR version 1.0 and version 1.1 options
+.br
+[-o \fIorientation\fP]
+[-s \fIsize\fP]
+[-x] [-y]
 .SH DESCRIPTION
 .I Xrandr
-is used to set the screen size, orientation and/or reflection.
-The
-.I -s
-option is a small integer index used to specify which size the screen should be set to.
-To find out what sizes are available, use the
-.I -q
-option, which reports the sizes available, the current rotation, and
-the possible rotations and reflections.
-The default size is the first size specified in the list.
-The
-.I -o
-option is used to specify the orientation of the screen,
-and can be one of
-\fI"normal inverted left right 0 1 2 3"\fP.
-.PP
-The
-.I -x
-option instructs the server to reflect the screen on the X axis.
-The
-.I -y
-option instructs the server to reflect the screen on the Y axis.
-Reflection is applied after rotation.
-.PP
-The
-.I -help
-option prints out a usage summary.
-The
-.I --verbose
-option tells you what xrandr is doing, selects for events, and tells you
-when events are received to enable debugging.
-.SH "RANDR 1.2"
-.PP
-Randr version 1.2 adds numerous new capabilities to the extension which 
-are supported by new options to the xrandr program.
-.PP
-The
-.I --fb
-option sets the new pixel size of the screen (e.g. --fb 320x200). If left unspecified, the
-screen is set to just fit the specified outputs.
-The 
-.I --dpi
-option changes the dpi of the screen (e.g. -dpi 96). If left unspecified,
-the dpi is left unchanged by any screen size changes.
+is used to set the size, orientation and/or reflection of the outputs for a
+screen. It can also set the screen size.
+There are a few global options; the rest modify a particular output and
+follow the specification of that output on the command line.
+.IP --help
+Print out a summary of the usage and exit.
+.IP --verbose
+causes xrandr to be more verbose. When used with -q (or without other
+options), xrandr will display more information about the server state. When
+used along with options that reconfigure the system, progress will be
+reported while executing the configuration changes.
+.IP -q
+When this option is present, or when no configuration changes are requested,
+xrandr will display the current state of the system.
+.IP "-screen \fIsnum\fP"
+This option selects which screen to manipulate. Note this refers to the X
+screen abstraction, not the monitor (or output).
+.SH "RandR version 1.1 options"
+These options are only available for X server supporting RandR version 1.2
+or newer.
+.IP --prop
+This option causes xrandr to display the contents of properties for each
+output. --verbose also enables --prop.
+.IP "--fb <width>x<height"
+Reconfigures the screen to the specified size. All configured monitors must
+fit within this size. When this option is not provided, xrandr computes the
+smallest screen size that will hold the set of configured outputs; this
+option provides a way to override that behaviour.
+.IP "--fbmm <width>x<height"
+Sets the reported values for the physical size of the screen. Normally,
+xrandr resets the reported physical size values to keep the DPI constant.
+This overrides that computation.
+.IP "--dpi <dpi>"
+This also sets the reported physical size values of the screen, it uses the
+specified DPI value to compute an appropriate physical size using whatever
+pixel size will be set.
 .PP
-The
-.I --output
-option selects an output (either by name or XID in hex) to change with any
-of the following parameters. More than one output may be changed per
-invocation.
-.SH "OUTPUT OPTIONS"
+.B "Per-output options"
+.IP "--output <output>"
+Selects an output to reconfigure. Use either the name of the output or the
+XID.
+.IP --auto
+For connected but disabled outputs, this will enable them using their
+preferred mode (or, something close to 96dpi if they have no preferred
+mode). For disconnected but enabled outputs, this will disable them.
+.IP "--mode <mode>"
+This selects a mode. Use either the name or the XID for <mode>
+.IP "--preferred"
+This selects the same mode as --auto, but it doesn't automatically enable or
+disable the output.
+.IP "--pos <x>x<y>"
+Position the output within the screen using pixel coordinates.
+.IP "--rate <rate>
+This marks a preference for refresh rates close to the specified value, when
+multiple modes have the same name, this will select the one with the nearest
+refresh rate.
+.IP "--reflect \fIreflection\fP"
+Reflection can be one of 'normal' 'x', 'y' or 'xy'. This causes the output
+contents to be reflected across the specified axes.
+.IP "--rotate \fIrotation\fP"
+Rotation can be one of 'normal', 'left', 'right' or 'inverted'. This causes
+the output contents to be rotated in the specified direction.
+.IP "--left-of, --right-of, --above, --below <another output>"
+Use one of these options to position the output relative to the position of
+another output. This allows convenient tiling of outputs within the screen.
+The position is always computed relative to the new position of the other
+output, so it is not valid to say --output a --left-of b --output 
+b --left-of a.
+.IP "--off"
+Disables the output.
+.IP "--crtc <crtc>"
+Uses the specified crtc (either as an index in the list of CRTCs or XID).
+In normal usage, this option is not required as xrandr tries to make
+sensible choices about which crtc to use with each output. When that fails
+for some reason, this option can override the normal selection.
 .PP
-The
-.I --crtc
-option specifies the desired crtc by XID. If left unspecified, an unused
-crtc is selected.
-The
-.I --mode
-option selects the desired output mode, either by name or XID. If left
-unspecified, the mode will be left unchanged.
-The
-.I --pos
-option selects where to position the output within the screen (e.g. --pos
-320x0). If left unspecified, the position will be left unchanged, or set to
-0x0 if the output is currently disabled.
-The
-.I --off
-option disables the specified output completely.
+.SH "RandR version 1.2 options"
+These options are available for X server supporting RandR version 1.1 or
+older. They are still valid for newer X servers, but they don't 
+.IP "-s <size index> or -s <width>x<height>"
+This sets the screen size, either matching by size or using the index into
+the list of available sizes.
+.IP "-o \fIrotation\fP"
+This specifies the orientation of the screen,
+and can be one of normal, inverted, left or right.
+.IP -x
+Reflect across the X axis.
+.IP -y
+Reflect across the Y axis.
 .SH "SEE ALSO"
 Xrandr(3)
 .SH AUTHORS
 Keith Packard,
+Open Source Technology Center, Intel Corporation.
 and
 Jim Gettys, 
 Cambridge Research Laboratory, HP Labs, HP.