xorg: Changes to 'xsf-docs'
xsf-docs/howto/build-mesa.mdwn | 201 +++++++++++++++++++++++++++++++++++
xsf-docs/howto/configure-input.mdwn | 176 ++++++++++++++++++++++++++++++
xsf-docs/howto/report-bugs.mdwn | 35 ++++++
xsf-docs/howto/triage-bugs.mdwn | 93 ++++++++++++++++
xsf-docs/howto/use-gdb.mdwn | 102 +++++++++++++++++
xsf-docs/howto/use-xrandr.mdwn | 173 ++++++++++++++++++++++++++++++
xsf-docs/howtos | 1
xsf-docs/howtos/build-mesa.mdwn | 201 -----------------------------------
xsf-docs/howtos/configure-input.mdwn | 176 ------------------------------
xsf-docs/howtos/report-bugs.mdwn | 35 ------
xsf-docs/howtos/triage-bugs.mdwn | 93 ----------------
xsf-docs/howtos/use-gdb.mdwn | 102 -----------------
xsf-docs/howtos/use-xrandr.mdwn | 173 ------------------------------
xsf-docs/index.mdwn | 16 +-
14 files changed, 789 insertions(+), 788 deletions(-)
New commits:
commit a6a400729c813eb8c2ce4b62b5bd022d889fd984
Author: Cyril Brulebois <kibi@debian.org>
Date: Tue Feb 15 22:09:35 2011 +0100
howtos: Rename to howto for consistency.
We have faq/ and reference/ as singular. Keep a symlink for now since
some mails to the BTS reference howtos/*.
diff --git a/xsf-docs/howto/build-mesa.mdwn b/xsf-docs/howto/build-mesa.mdwn
new file mode 100644
index 0000000..dc49cd9
--- /dev/null
+++ b/xsf-docs/howto/build-mesa.mdwn
@@ -0,0 +1,201 @@
+# How to build mesa
+
+Cyril Brulebois <kibi@debian.org>
+
+
+## Foreword
+
+Mesa is a special package since many flavours are built, which means
+it takes quite some time to get all packages ready, as well as some
+disc space (over 2GB for the `build/` directory alone).
+
+Also, trying to figure out whether latest `master` is also affected,
+or backporting some bug fixes might lead to some painful I/O while
+generating the `.deb` files, and then installing/unpacking them. This
+is why this document was written: Helping users test other mesa
+releases, branches, bug fixes without having to build full packages,
+and without having to mess with their systems (*i.e.* no root access
+is needed once the build dependencies are installed).
+
+We’ll focus on the DRI (Direct Rendering Infrastructure) flavour
+(`libgl1-mesa-dri`), which is the most common.
+
+It might be possible to adapt the following steps to another flavour,
+in which case the appropriate options to be passed to `./configure`
+should be looked up in the `debian/rules` file of the Debian source
+package.
+
+*Note:* Before reading further, be aware that `nouveau` is a bit
+ special.
+
+ * It’s considered experimental, and shipped in the
+ `libgl1-mesa-dri-experimental` package accordingly.
+ * It may fail to build (both API and ABI are still changing).
+ * We’re not shipping `nouveau_vieux_dri.so` yet (for cards from NV04
+ to NV2X; `nouveau_dri.so` is for NV30 and later). See the upstream
+ [FeatureMatrix](http://nouveau.freedesktop.org/wiki/FeatureMatrix)
+ page to determine a card’s series.
+
+
+## Gathering information
+
+Get started by installing `mesa-utils`, which contains `glxinfo`.
+
+ * *Is direct rendering enabled?*
+
+ $ glxinfo | grep ^direct
+ direct rendering: Yes
+
+ ↪ Yes.
+
+ * *Is this the classic or
+ [Gallium](http://en.wikipedia.org/wiki/Gallium3D) driver?*
+
+ $ glxinfo | grep 'renderer string'
+ OpenGL renderer string: Mesa DRI Intel(R) 945GM GEM 20100330 DEVELOPMENT
+
+ ↪ No “Gallium” here, therefore: “classic”.
+
+ * *Which driver is this, and where is it located?*
+
+ $ LIBGL_DEBUG=verbose glxinfo 2>&1 >/dev/null | grep so$
+ libGL: OpenDriver: trying /usr/lib/dri/tls/i915_dri.so
+ libGL: OpenDriver: trying /usr/lib/dri/i915_dri.so
+
+ ↪ `i915`, from the system directory: `/usr/lib/dri` (likely
+ installed through a Debian package).
+
+ * *How can I get more debugging information?*
+
+ export LIBGL_DEBUG=verbose
+ export MESA_DEBUG=1
+ export EGL_LOG_LEVEL=debug
+
+
+## Preparing mesa sources
+
+To get started, installing all build dependencies of the `mesa` source
+package should be sufficient, along with the essential build tools,
+and `git`:
+
+ $ sudo apt-get install build-essential git
+ $ sudo apt-get build-dep mesa
+
+If you’re on `squeeze` you may need to install a few more packages:
+newer `libdrm-dev` (**FIXME:** talk about picking it from `wheezy`? or
+about a local installation?), as well as `libxmu-dev`, `libxi-dev`.
+
+Make sure you have some disc space available, since the git repository
+is over 120MB, and since the mesa directory is over 500MB after a
+build. Once you’re ready, grab the upstream mesa sources:
+
+ $ git clone git://anongit.freedesktop.org/mesa/mesa mesa.git
+ $ cd mesa.git
+ $ autoreconf -vfi
+
+Here’s what the `./configure` call will look like:
+
+ $ ./configure --enable-driglx-direct \
+ --enable-gallium \
+ --enable-gles-overlay \
+ --enable-gles1 \
+ --enable-gles2 \
+ --enable-glx-tls \
+ --with-driver=dri \
+ --with-dri-driverdir=/usr/lib/dri \
+ --with-egl-platforms='drm x11' \
+ --with-state-trackers=egl,glx,dri,vega \
+ …
+
+Now, what are the parameters to replace “`…`” with? Basically, if
+you determined an Intel driver (`i915` or `i965`), you want to use the
+classic drivers and to disable the Gallium drivers. If you saw a
+Radeon driver (`r300` or `r600`), you should prefer the Gallium
+drivers. If you’re using `nouveau`, make sure you read the note in the
+**Foreword**. The following assumes you’re using `nouveau_dri.so`.
+
+
+Examples for common drivers:
+
+ * For `i915`, you need:
+
+ --with-dri-drivers=i915
+
+ * For `i965`, you need:
+
+ --with-dri-drivers=i965
+
+ * For `nouveau`, you may want to try:
+
+ --with-dri-drivers=nouveau --enable-gallium-nouveau
+
+ * For `r300` (the options are named `radeon`), you need:
+
+ --with-dri-drivers=radeon --enable-gallium-radeon
+
+ * For `r600`, you need:
+
+ --with-dri-drivers=r600 --enable-gallium-r600
+
+Now, once you’ve run `./configure`, time for your favorite beverage:
+
+ $ make
+
+
+## Running the newly-built mesa libraries
+
+Shared libraries end up in the `lib/` directory. It contains the
+classic drivers, while Gallium drivers end up under `lib/gallium`. If
+you’re not an Intel user, overwrite the classic drivers with the
+Gallium ones:
+
+ $ mv lib/gallium/* lib/
+
+Now, 3 variables need to be set, so that the locally-built libraries
+are used.
+
+ * To begin with, libGL itself and its drivers:
+
+ $ export LIBGL_DRIVERS_PATH=lib
+
+ *Did this work?*
+
+ $ LIBGL_DEBUG=verbose glxinfo 2>&1 >/dev/null | grep so$
+ libGL: OpenDriver: trying lib/tls/i915_dri.so
+ libGL: OpenDriver: trying lib/i915_dri.so
+
+ ↪ Yes: No system directory, paths are relative to `lib/`.
+
+ * Set `LD_LIBRARY_PATH` to make sure the locally-built libraries
+ (including those pulled through library dependencies) are used,
+ instead of system ones:
+
+ $ export LD_LIBRARY_PATH=lib
+
+ *Did this work?*
+
+ $ ldd lib/libGLESv2.so | grep glapi
+ libglapi.so.0 => lib/libglapi.so.0 (0x00007fee3192e000)
+
+ ↪ Yes: Path is relative to `lib`.
+
+ * Set the EGL search path:
+
+ $ export EGL_DRIVERS_PATH=lib/egl
+
+ *Did this work?*
+
+ **FIXME: We should be shipping EGL-aware applications through
+ `mesa-utils`.**
+
+ $ EGL_LOG_LEVEL=debug test_application 2>&1 >/dev/null | grep '\.so'
+ libEGL debug: added lib/egl/egl_gallium.so to module array
+ libEGL debug: dlopen(lib/egl/egl_gallium.so)
+ libEGL debug: DRI2: dlopen(lib/i915_dri.so)
+
+ ↪ Yes: No system directory, paths are relative to `lib/`.
+
+
+### The end.
+
+Now you should be ready to test upstream’s suggestions!
diff --git a/xsf-docs/howto/configure-input.mdwn b/xsf-docs/howto/configure-input.mdwn
new file mode 100644
index 0000000..75ea3c3
--- /dev/null
+++ b/xsf-docs/howto/configure-input.mdwn
@@ -0,0 +1,176 @@
+# How to configure input
+
+Cyril Brulebois <kibi@debian.org>
+
+
+## General considerations
+
+### Foreword
+
+The Debian wiki also contains an
+[inupt hotplug guide](http://wiki.debian.org/XStrikeForce/InputHotplugGuide)
+which contains some context around X’s input subsystem. The present
+document is meant to be an executive summary, and might miss some
+bits. (**FIXME:** Merge those bits.)
+
+
+### Rules of thumb
+
+In this documentation, only the last part of the driver’s name will be
+mentioned, all of them are under the `xserver-xorg-input-*` namespace.
+
+ * On Linux, `evdev` is used for both keyboard and mouse
+ input.
+ * On Linux as well, `synaptics` can be used to benefit from extra
+ features; it takes precedence over `evdev` automatically if both
+ are installed.
+ * On GNU/kFreeBSD and GNU/Hurd, `kbd` handles the keyboard and
+ `mouse` handles mice, unsurprisingly.
+
+
+### Configuration snippets
+
+X can now be run without `xorg.conf`, but sometimes one has to
+configure a few settings for this or that driver. Starting with
+`squeeze`, that can be done by adding a file under
+`/etc/X11/xorg.conf.d`, with a `.conf` suffix, as documented in the
+`xorg.conf` manpage.
+
+Some packages ship a default configuration file under
+`/usr/share/X11/xorg.conf.d` with general rules to match appropriate
+hardware. The files under `/etc/X11/xorg.conf.d` take precedence, as
+documented in the `xorg.conf` manpage.
+
+It’s probably mostly useful in the `synaptics` case, in case one wants
+to change default settings on a system-wide fashion. See the **Pointer
+configuration** section below for an example.
+
+
+## Basic keyboard configuration
+
+The `keyboard-configuration` package ships `/etc/default/keyboard`
+which can be used to set the following `xkb` items: model, layout,
+variant, and options. Here’s an example:
+
+ XKBMODEL="pc105"
+ XKBLAYOUT="fr"
+ XKBVARIANT="oss"
+ XKBOPTIONS="compose:menu,terminate:ctrl_alt_bksp"
+
+Quick words about the options:
+
+ * They are comma-separated.
+ * The list of options and a short description for each can be found
+ in the `/usr/share/X11/xkb/rules/base.lst` file (shipped by the
+ `xkb-data` package).
+ * First option: `compose:menu`. This sets the `menu` key as the
+ Compose key. More information about it can be found in the
+ `Compose` manpage.
+ * Second option: `terminate:ctrl_alt_bksp`. By default, the X server
+ is no longer killed through `Ctrl+Alt+Backspace`. This option
+ restores the old behaviour.
+
+Two ways to change the configuration:
+
+ * `dpkg-reconfigure keyboard-configuration` is going to ask questions
+ through debconf prompts.
+ * Manually editing `/etc/default/keyboard` also works.
+
+How does it propagate to X?
+
+ * When HAL is used (that is: on GNU/kFreeBSD and GNU/Hurd), one has
+ to restart it: `invoke-rc.d hal restart`
+ * When udev is used (on GNU/Linux, starting with `squeeze`), one has
+ to tell udev to reload input-related configuration:
+ `udevadm trigger --subsystem-match=input --action=change`
+ (that can be found in `keyboard-configuration`’s `README.Debian`
+ file). Properties attached to the input devices are then updated,
+ and X uses those properties when it starts, as can be seen by
+ searching for `xkb_` in the X log. Please note that trying
+ `invoke-rc.d udev restart` changes nothing, one has to use
+ `udevadm`. Properties can be inspected through:
+ `/sbin/udevadm info --export-db`
+
+
+## Pointer configuration
+
+### evdev configuration
+
+Available options are documented in the `evdev` manpage. Let’s check
+what a configuration snippet (mentioned in **General considerations**)
+would look like. Here is a fictional `/etc/X11/xorg.conf.d/42-evdev.conf`:
+
+ Section "InputClass"
+ Identifier "evdev pointer tweaked catchall"
+ MatchIsPointer "on"
+ Driver "evdev"
+ Option "Emulate3Buttons" True"
+ Option "SwapAxes" "True"
+ EndSection
+
+Line by line walkthrough:
+
+ * To avoid specifying any device under `/dev/input` (`event$N` might
+ change, remember it’s about hotplug support!), we use an
+ `InputClass`.
+ * We need an identifier, the actual name doesn’t matter.
+ * We match everything that looks like a touchpad. Meaning no generic
+ pointer, keyboard, or tablet.
+ * We specify the driver we want to use for the matched device(s).
+ * Finally the options we want to set. Here we enable the 3rd button
+ emulation (clicking left and right buttons at the same time then no
+ longer acts as if the middle button was clicked). Then we swap x
+ and y axes, just for the fun of it.
+
+
+### synaptics configuration
+
+The `synaptics` driver comes with two tools. The more interesting one
+is `synclient`, which can be used to list available options and
+current settings: `synclient -l`. The documentation for each option
+can be found in the `synaptics` manpage.
+
+`synclient` can also be used to set options. A common example is
+enabling tapping (upstream kept it disabled by default, Debian won’t
+deviate, no need to file bugs): `synclient TapButton1=1`; one can also
+disable the touchpad temporarily: `synclient TouchpadOff=1` to
+disable it, `synclient TouchpadOff=0` to enable it again.
+
+Let’s check what a configuration snippet (mentioned in **General
+considerations**) would look like. Here is a fictional
+`/etc/X11/xorg.conf.d/42-synaptics.conf`:
+
+ Section "InputClass"
+ Identifier "touchpad tweaked catchall"
+ MatchIsTouchpad "on"
+ Driver "synaptics"
+ Option "TapButton1" "1"
+ Option "HorizEdgeScroll" "1"
+ EndSection
+
+Line by line walkthrough:
+
+ * To avoid specifying any device under `/dev/input` (`event$N` might
+ change, remember it’s about hotplug support!), we use an
+ `InputClass`.
+ * We need an identifier, the actual name doesn’t matter.
+ * We match everything that looks like a touchpad. Meaning no generic
+ pointer, keyboard, or tablet.
+ * We specify the driver we want to use for the matched device(s).
+ * Finally the options we want to set. We enable tapping for the first
+ button. And we enable horizontal scrolling (by default, only
+ vertical scrolling is enabled).
+
+Settings can also be changed by various settings managers, like
+Gnome’s or KDE’s. An example of a graphical user interface making it
+possible to set options in a clicky way: `gpointing-device-settings`.
+
+There’s a palm detection setting but that relies on hardware/firmware
+support for the touchpad. The other tool shipped with the `synaptics`
+driver is `syndaemon`, which makes it trivial to disable the touchpad
+temporarily, when the keyboard is being used. Here’s an example:
+`syndaemon -d -i 0.5` makes `syndaemon` start in background (`-d` for
+daemon mode), waiting 0.5 second before enabling the touchpad again
+after the last keypress. Warning: it becomes quite difficult to use
+things like `Ctrl+click` in a browser, or `Alt+drag` to move
+windows.
diff --git a/xsf-docs/howto/report-bugs.mdwn b/xsf-docs/howto/report-bugs.mdwn
new file mode 100644
index 0000000..6fc7140
--- /dev/null
+++ b/xsf-docs/howto/report-bugs.mdwn
@@ -0,0 +1,35 @@
+# How to report bugs
+
+Cyril Brulebois <kibi@debian.org>
+
+
+## Simple as reportbug
+
+### Initial report
+
+Unless you know which package to report the bug against, you can
+report the bug against the `xorg` metapackage:
+
+ reportbug xorg
+
+Like most packages related to the X server, reporting a bug against
+this package triggers a bug script which is going to collect X-related
+information, be it installed packages, running kernel, X
+configuration, X log, and so on.
+
+Note: In case this metapackage wasn’t used to install your X stack,
+report a bug against `xserver-xorg` instead. And if that one isn’t
+installed either, go for `xserver-xorg-core`.
+
+
+### Follow-up with more info
+
+If you reported a bug against another package and if that bug was
+reassigned to an X-related package, we might need more
+information. You can run the bug script manually and attach its output
+to your mail to the bug report:
+
+ /usr/share/bug/xserver-xorg-core/script 3>/tmp/script.log
+
+Note: Make sure there’s no space between `3` and `>`, that’s a shell
+redirection.
diff --git a/xsf-docs/howto/triage-bugs.mdwn b/xsf-docs/howto/triage-bugs.mdwn
new file mode 100644
index 0000000..e523584
--- /dev/null
+++ b/xsf-docs/howto/triage-bugs.mdwn
@@ -0,0 +1,93 @@
+# How to triage bugs
+
+Cyril Brulebois <kibi@debian.org>
+
+
+## Packaging bugs or upstream bugs?
+
+It’d be nice to get all upstream bugs tagged as such (`upstream` tag),
+forwarded upstream (which means the bugzilla instance on
+<http://bugs.freedesktop.org/> for most packages), and marked as such.
+
+A mail to `control@bugs.debian.org` would look like:
+
+ tag X upstream
+ forwarded X https://bugs.freedesktop.org/show_bug.cgi?id=Y
+ thanks
+
+Then [`bts-link`](http://bts-link.alioth.debian.org/) comes into play
+and help us tracking upstream status, which is pretty nice to have.
+
+
+## Usertags
+
+Another feature of the BTS is usertagging. That lets people keep track
+of additional tags, “attached” to a given mail address. For XSF,
+that’s `debian-x@lists.debian.org`.
+
+The list of all usertagged bugs can be seen on the following page; the
+list of all used usertags is at the bottom, in the form.
+→ <http://bugs.debian.org/cgi-bin/pkgreport.cgi?users=debian-x@lists.debian.org>
+
+Let’s give some examples:
+
+ * `i810`, `i915`: helps triaging `-video-intel` bugs depending on the
+ chipset.
+ * `r200`, `r300`: ditto for `-video-ati`.
+ * `xset`, `xrandr`: helps triaging `x11-xserver-utils` bugs depending
+ on the affected tool (like other `x11-*` packages, that’s a bundle
+ of teeny tiny apps).
+ * `squeeze-candidate`: helps keeping a list of bugs we’d like to get
+ fixed in a point release (through a stable update).
+ * `needs-forwarding`: of course, it’d be nice to have all upstream
+ bugs reported upstream, but some might need special attention
+ (*e.g.* security bugs).
+
+Here’s an example of URL, for the last tags:
+→ <http://bugs.debian.org/cgi-bin/pkgreport.cgi?users=debian-x@lists.debian.org&tag=squeeze-candidate>
+→ <http://bugs.debian.org/cgi-bin/pkgreport.cgi?users=debian-x@lists.debian.org&tag=needs-forwarding>
+
+By the way one should keep an eye on the list of found/fixed
+versions since those bugs are likely marked as resolved (in `unstable`
+or `experimental`), but might still affect a stable release. Maybe we
+just need to have both `squeeze-candidate` and `squeeze-accepted`, and
+swap usertags when the stable upload happens.
+
+
+## Categories
+
+The BTS has yet another feature which can help, categories. That’s
+based on usertags as well, but one has to use the package address
+(`$package@packages.debian.org`), so that’s package-specific rather
+than team-specific.
+
+Categories are
+[documented on the wiki](http://wiki.debian.org/bugs.debian.org/usertags),
+and they would probably be welcome in the `intel` and `ati` cases
+above, as well as in the “multiple tools in a single bundle”
+cases… An example of what we could achieve is the
+[devscripts bug page](http://bugs.debian.org/devscripts) (it takes
+some time to load, plenty of bugs).
+
+Needed steps for that to happen:
+
+ * create usercategories.
+ * move usertags from `debian-x@lists.debian.org` to
+ `$package@packages.debian.org`, probably using the `bts select`
+ command to get the list over which to iterate.
+ * profit!
+
+To move the usertags, something like that should do the job:
+
+ # Adding usertags:
+ user $package1@packages.debian.org
+ usertag X xset
+ usertag Y xrandr
+ user $package2@packages.debian.org
+ usertag Z i810
+
+ # Removing tags which are no longer needed:
+ user debian-x@lists.debian.org
+ usertag X - xset
+ usertag Y - xrandr
+ usertag Z - i810
diff --git a/xsf-docs/howto/use-gdb.mdwn b/xsf-docs/howto/use-gdb.mdwn
new file mode 100644
index 0000000..df7152d
--- /dev/null
+++ b/xsf-docs/howto/use-gdb.mdwn
@@ -0,0 +1,102 @@
+# How to use gdb
+
+Cyril Brulebois <kibi@debian.org>
+
+
+## Foreword
+
+One should note that X is responsible for VT switching, meaning
+switching between an X session and console terminals. In other words,
+`Ctrl+Alt+Fn` is handled by X. If X is stopped, for example because
+it’s running under `gdb`, one can no longer switch to another
+VT. That’s why we’re recommending using a second machine to debug
+X. Nevertheless, here are some instructions to attempt debugging X
+with a single machine.
+
+### One-machine approach
+
+From a console (let’s assume it’s `vt1`), open a `root`
+terminal. Then, start a loop which will bring you back to this console
+after a given delay (in the following example, every 60 seconds), just
+in case. The ampersand (`&`) at the end makes it a background job.
+
+ while :; do sleep 60; chvt 1; done &
+
+### Two-machine approach
+
+That’s simpler, but then you need a second machine. Just log into the
+first machine from the second one, using `ssh`.
+
+### Needed packages
+
+Obviously, `gdb` is needed; `xserver-xorg-core-dbg` contains the
+debugging symbols for the server itself. Other needed packages can be
+determined by looking at the backtrace. **FIXME: More info about
+that.**
+
+## Actual gdb work
+
+### Attaching X from gdb
+
+The way of starting X doesn’t really matter, as `gdb` makes it
+possible to attach a running process. If there’s a single X instance
+running, that will do the job:
+
+ # gdb attach $(pidof X)
+ [---GDB starts---]
+ (gdb) handle SIGPIPE nostop
+ (gdb) cont
+
+If there are several instances, one can use `ps aux` to determine the
+PID of the appropriate instance (2nd column → `$pid`), and then attach
+it:
+
+ # gdb attach $pid
+ [---GDB starts---]
+ (gdb) handle SIGPIPE nostop
+ (gdb) cont
+
+### Starting X from gdb
+
+In case X crashes at start-up, one can start X from `gdb` in the
+following way. In this example, the only parameter is the display, but
+more parameters can be added.
+
+ # gdb --args Xorg :0
+ [---GDB starts---]
+ (gdb) handle SIGPIPE nostop
+ (gdb) run
+
+### What is SIGPIPE?
+
+`SIGPIPE` is a signal that can reach the X server quite easily,
+especially when performing a VT switch, or refreshing large parts of
+the screen. That’s why we ask `gdb` not to stop when such a signal is
+caught, thanks to the `handle SIGPIPE nostop` command.
+
+### How to display a backtrace?
+
+Once X is crashed, for example because it received a `SIGSEGV`
+(segmentation fault, usually because of a NULL pointer dereference),
+or a `SIGBUS`, one gets back to the `gdb` prompt. One can then request
+a backtrace (`bt`) or a full backtrace (`bt full`). The latter is what
+developers are usually interested in, because variable values are also
+available.
+
+ (gdb) bt
+ (gdb) bt full
+
+### How to save a backtrace?
+
+To save a recording of the gdb session to a file (`gdb.txt` by
+default):
+
+ (gdb) set logging on
+
+To save in a different file, use this instead:
+
+ (gdb) set logging file my-file.txt
+ (gdb) set logging on
+
+Once logging is enabled, you can request a (full) backtrace using the
+previous commands.
diff --git a/xsf-docs/howto/use-xrandr.mdwn b/xsf-docs/howto/use-xrandr.mdwn
new file mode 100644
index 0000000..a3293a0
--- /dev/null
+++ b/xsf-docs/howto/use-xrandr.mdwn
@@ -0,0 +1,173 @@
+# How to use xrandr
+
+Cyril Brulebois <kibi@debian.org>
+
+
+## Getting started
+
+### What is xrandr?
+
+`xrandr` is a command-line tool to interact with the X `RandR`
+extension [see [x.org](http://www.x.org/wiki/Projects/XRandR),
+[wikipedia](http://en.wikipedia.org/wiki/RandR)], which allows for
+live (re)configuration of the X server (*i.e.* without restarting it):
+It provides automatic discovery of modes (resolutions, refresh rates,
+etc.) together with the ability to configure outputs dynamically
+(resize, rotate, move, etc.).
+
+**FIXME: Status across drivers?**
+
+### What consequences for xorg.conf?
+
+Starting with `squeeze`, removing the `xorg.conf` configuration file
+entirely should work well enough, but in case that doesn’t work out,
+let’s document what can be removed from it from a `RandR` point of
+view.
+
+With the driver detecting modes automatically, several configuration
+options become useless most of the time in your configuration file
+(xorg.conf). You might want to remove:
+
+ * `HorizSync` and `VertRefresh` from the `Monitor` section.
+ * Modes from `Display` subsection in `Screen` section.
+ * `ModeLine` from the `Monitor` section.
+
+There’s also no need to keep static dual-head configuration. Some
+suggestions to get a tiny `xorg.conf`:
+
+ * Drop dual `Device`/`Screen`/`Monitor` sections, a single one is
+ needed.
+ * Drop `MonitorLayout` option and `Screen` lines from the remaining
+ `Device` section.
+ * Drop the `ServerLayout` section(s).
+ * Drop `RightOf`/`LeftOf` indication of the remaining `Screen` line
+ in `ServerLayout` section.
+
+## Basic xrandr usage
+
+Once the configuration file (`xorg.conf`) is removed or updated,
+starting the server should enable some outputs by default. Their
+top-left corners will be at the same part of the image, but their
+modes will probably be different.
+
+All outputs may be configured through `xrandr`. To see the available
+outputs, just run `xrandr`:
+
+ $ xrandr
+ Screen 0: minimum 320 x 200, current 1280 x 800, maximum 4096 x 4096
+ VGA1 disconnected (normal left inverted right x axis y axis)
+ LVDS1 connected 1280x800+0+0 inverted X and Y axis (normal left inverted right x axis y axis) 261mm x 163mm
+ 1280x800 59.8*+
+ 1024x768 60.0
+ 800x600 60.3 56.2
+ 640x480 59.9
+ DVI1 disconnected (normal left inverted right x axis y axis)
+ TV1 disconnected (normal left inverted right x axis y axis)
+
+Comments:
+
+ * We see 4 outputs: `VGA1`, `LVDS1`, `DVI1`, `TV1`.
+ * Only the internal panel (`LVDS1`) is connected and it supports 4
+ modes at 60 Hz, 1 mode at 56 Hz.
+ * The mode marked with a star (`*`) is the current mode.
+ * The one marked with a plus (`+`) is the preferred one. Most
+ monitors report a preferred mode to the driver. And the
+ server/driver will generally choose it by default.
+
+**FIXME: Mention output name conventions?**
+
+When manipulating `VGA1` output properties, you should use:
+
+ $ xrandr --output VGA1 <options>
+
+### Adding/removing heads dynamically
+
+The old days where you had to restart X when plugging a new monitor
+are gone. With `RandR` 1.2, you can plug/unplug monitors whenever you
+want. Running the following line will query all outputs and enable
+them with their default mode:
+
+ $ xrandr --auto
+
+You may also disable one output using:
+
+ $ xrandr --output LVDS1 --off
+
+This may be useful for some buggy application that don’t support
+multiple outputs well. Also, due to CRTC limitations (see the Caveats
+section below), it is often required to disable one output before
+enabling another since most hardware only support 2 at the same time.
+
+### Changing the mode
+
+With the above `xrandr` output, you may change the `LVDS1` mode to
+`1024x768` using:
+
+ $ xrandr --output LVDS1 --mode 1024x768
+
+The refresh rate may also be changed, either at the same time or
+independently:
+
+ $ xrandr --output LVDS1 --mode 1024x768 --rate 75
+ $ xrandr --output LVDS1 --rate 75
+
+To get back to the default mode:
+
+ $ xrandr --output LVDS1 --auto
+
+## Placing outputs in a virtual screen
+
+### A bit of configuration for non-KMS setups:
+
+Let’s have a look at the maximal virtual screen size, we see
+`4096x4096` in this example:
+
+ $ xrandr|head -1
+ Screen 0: minimum 320 x 200, current 1280 x 800, maximum 4096 x 4096
+
+With KMS (**FIXME: Link to a page which explains what KMS is**),
+there's no need to specify any `Virtual` option. With DRI and without
+KMS, that might be needed. Indeed, drivers will often create a default
+virtual screen with small dimensions, for instance `1600x1200`, to
+reduce memory consumption.
+
+If you plan to use multiple outputs displaying different zones, you
+should configure your `xorg.conf` by adding a `Virtual` line to the
+`Display` subsection in the `Screen` section.
+
+ Section "Screen"
+ ...
+ SubSection "Display"
+ Depth 24
+ Virtual 3000 2000
+ EndSubSection
+ EndSection
+
+### Place outputs
+
+Outputs are placed using the following options:
+`--right-of`/`--left-of`/`--above`/`--below`. For instance, to place
+the `VGA1` output virtually-right of the internal panel (`LVDS1`):
+
+ $ xrandr --output VGA1 --right-of LVDS1
+
+Note that hardware and memory limitations may severely restrict the
+size of your virtual screen, see the Caveats section below.
+
+## Adding new modes
+
+Under some circumstances, some modes might be missing. For instance,
+if the monitor does not report correct EDID information. Or if the
+output didn't have a CRTC available at startup because another output
+was using it and you disabled it in the meantime.
+
+If a mode exist, you may add it to one output with:
+
+ $ xrandr --addmode VGA1 800x600
+
+If the mode does not exist, you may first create it by passing a modeline:
+
+ $ xrandr --newmode <ModeLine>
+
+You may create a modeline using the `gtf` or `cvt` tools (shipped in
+the `xserver-xorg-core` package).
diff --git a/xsf-docs/howtos b/xsf-docs/howtos
new file mode 120000
index 0000000..c953de0
--- /dev/null
+++ b/xsf-docs/howtos
@@ -0,0 +1 @@
+howto
\ No newline at end of file
diff --git a/xsf-docs/howtos/build-mesa.mdwn b/xsf-docs/howtos/build-mesa.mdwn
deleted file mode 100644
index dc49cd9..0000000
--- a/xsf-docs/howtos/build-mesa.mdwn
+++ /dev/null
@@ -1,201 +0,0 @@
-# How to build mesa
-
-Cyril Brulebois <kibi@debian.org>
-
-
-## Foreword
-
-Mesa is a special package since many flavours are built, which means
-it takes quite some time to get all packages ready, as well as some
-disc space (over 2GB for the `build/` directory alone).
-
-Also, trying to figure out whether latest `master` is also affected,
-or backporting some bug fixes might lead to some painful I/O while
-generating the `.deb` files, and then installing/unpacking them. This
-is why this document was written: Helping users test other mesa
-releases, branches, bug fixes without having to build full packages,
-and without having to mess with their systems (*i.e.* no root access
-is needed once the build dependencies are installed).
-
-We’ll focus on the DRI (Direct Rendering Infrastructure) flavour
-(`libgl1-mesa-dri`), which is the most common.
-
-It might be possible to adapt the following steps to another flavour,
-in which case the appropriate options to be passed to `./configure`
-should be looked up in the `debian/rules` file of the Debian source
-package.
-
-*Note:* Before reading further, be aware that `nouveau` is a bit
- special.
-
- * It’s considered experimental, and shipped in the
- `libgl1-mesa-dri-experimental` package accordingly.
- * It may fail to build (both API and ABI are still changing).
- * We’re not shipping `nouveau_vieux_dri.so` yet (for cards from NV04
- to NV2X; `nouveau_dri.so` is for NV30 and later). See the upstream
- [FeatureMatrix](http://nouveau.freedesktop.org/wiki/FeatureMatrix)
- page to determine a card’s series.
-
-
-## Gathering information
-
-Get started by installing `mesa-utils`, which contains `glxinfo`.
-
- * *Is direct rendering enabled?*
-
- $ glxinfo | grep ^direct
- direct rendering: Yes
-
- ↪ Yes.
-
- * *Is this the classic or
- [Gallium](http://en.wikipedia.org/wiki/Gallium3D) driver?*
-
- $ glxinfo | grep 'renderer string'
- OpenGL renderer string: Mesa DRI Intel(R) 945GM GEM 20100330 DEVELOPMENT
-
- ↪ No “Gallium” here, therefore: “classic”.
-
- * *Which driver is this, and where is it located?*
-
- $ LIBGL_DEBUG=verbose glxinfo 2>&1 >/dev/null | grep so$
- libGL: OpenDriver: trying /usr/lib/dri/tls/i915_dri.so
- libGL: OpenDriver: trying /usr/lib/dri/i915_dri.so
-
- ↪ `i915`, from the system directory: `/usr/lib/dri` (likely
- installed through a Debian package).
-
- * *How can I get more debugging information?*
-
- export LIBGL_DEBUG=verbose
- export MESA_DEBUG=1
- export EGL_LOG_LEVEL=debug
-
-
-## Preparing mesa sources
-
-To get started, installing all build dependencies of the `mesa` source
-package should be sufficient, along with the essential build tools,
-and `git`:
-
- $ sudo apt-get install build-essential git
- $ sudo apt-get build-dep mesa
-
-If you’re on `squeeze` you may need to install a few more packages:
-newer `libdrm-dev` (**FIXME:** talk about picking it from `wheezy`? or
-about a local installation?), as well as `libxmu-dev`, `libxi-dev`.
-
-Make sure you have some disc space available, since the git repository
-is over 120MB, and since the mesa directory is over 500MB after a
-build. Once you’re ready, grab the upstream mesa sources:
-
- $ git clone git://anongit.freedesktop.org/mesa/mesa mesa.git
- $ cd mesa.git
- $ autoreconf -vfi
-
-Here’s what the `./configure` call will look like:
-
- $ ./configure --enable-driglx-direct \
- --enable-gallium \
- --enable-gles-overlay \
- --enable-gles1 \
- --enable-gles2 \
- --enable-glx-tls \
- --with-driver=dri \
- --with-dri-driverdir=/usr/lib/dri \
- --with-egl-platforms='drm x11' \
- --with-state-trackers=egl,glx,dri,vega \
- …
-
-Now, what are the parameters to replace “`…`” with? Basically, if
-you determined an Intel driver (`i915` or `i965`), you want to use the
-classic drivers and to disable the Gallium drivers. If you saw a
-Radeon driver (`r300` or `r600`), you should prefer the Gallium
-drivers. If you’re using `nouveau`, make sure you read the note in the
-**Foreword**. The following assumes you’re using `nouveau_dri.so`.
-
-
-Examples for common drivers:
-
- * For `i915`, you need:
-
- --with-dri-drivers=i915
-
- * For `i965`, you need:
-
- --with-dri-drivers=i965
-
- * For `nouveau`, you may want to try:
-
- --with-dri-drivers=nouveau --enable-gallium-nouveau
-
- * For `r300` (the options are named `radeon`), you need:
-
- --with-dri-drivers=radeon --enable-gallium-radeon
-
- * For `r600`, you need:
-
- --with-dri-drivers=r600 --enable-gallium-r600
-
-Now, once you’ve run `./configure`, time for your favorite beverage:
-
- $ make
-
-
Reply to: