README.rst

   1 DSL - easy Display Setup for Laptops
   2 ====================================
   3
   4 Introduction
   5 ------------
   6
   7 This is the documentation of DSL_, a tool to setup screens on a Linux-powered
   8 Laptop.
   9
  10 DSL is targeted for a specific use-case: The laptop is used both with the
  11 internal screen only, and in combination with a single external screen.
  12 xrandr_ is used to detect whether an external screen is plugged in, and
  13 to change the configuration according to the user's specification.
  14
  15 .. _DSL: https://www.ralfj.de/projects/dsl
  16 .. _xrandr: http://www.x.org/wiki/Projects/XRandR
  17
  18 Usage
  19 -----
  20
  21 DSL features an interactive and a batched mode of use.
  22 Either way, of DSL is started while no external screen is connected, it
  23 enables the internal screen. It also resets the backlight to 100%, as some
  24 laptops keep the backlight off if it was turned off by power-saving features.
  25
  26 It is in the case that an external screen is plugged in that the two modes
  27 differ.
  28
  29 Simply run ``dsl.py`` to start the interactive mode. A window will pop up,
  30 allowing you to select the resolution of the external screen and where it
  31 will appear relative to the laptop. The option ``--frontend`` (or ``-f``) can
  32 be used to choose the frontend which opens the window. Currently, the
  33 frontends ``qt`` and ``zenity`` are available. DSL attempts to choose an
  34 adequate frontend automatically.
  35
  36 The option ``--relative-position`` (``-f``) suppresses the interactive
  37 configuration. Instead, the given given option (``left``, ``right`` or
  38 ``external-only``) is applied with the default resolution of the external
  39 screen.
  40
  41 Finally, the flag ``--internal-only`` (``-i``) tells DSL to ignore the
  42 external screen and enable the internal one.
  43
  44 Automatic Configuration
  45 -----------------------
  46
  47 In combination with x-on-resize_ by Keith Peckard, DSL can automatically
  48 pop-up when a screen is plugged in, and automatically re-enable the internal
  49 screen the external one is plugged off.
  50
  51 Besides, you may want to apply some configuration without pop-up if an
  52 external screen is plugged in when you log in to your desktop environment.
  53
  54 All this is achieved by running the following shell script on log-in::
  55
  56   DSL=/path/to/dsl.py
  57   x-on-resize -c $DSL
  58   $DSL -r external-only
  59
  60 .. _x-on-resize: http://keithp.com/blogs/x-on-resize/
  61
  62 Configuration File
  63 ------------------
  64
  65 You can use ``~/.dsl.conf`` to tell DSL which are the names of your internal
  66 and external connectors. These are the names as used by ``xrandr``.
  67 The option ``internalConnector`` gives the name of the xrandr connector
  68 corresponding to your internal laptop screen. All the others will be
  69 considered external screens, unless you use the option ``externalConnectors``
  70 to prove a (space-separated) list of connectors to be considered external by
  71 DSL. Any connector not mentioned in either option will be completely ignored.
  72
  73 Source, License
  74 ---------------
  75
  76 You can find the sources in the `git repository`_. They are provided under
  77 the GPLv2_ or (at your option) any later version of the GPL.
  78
  79 .. _git repository: http://www.ralfj.de/git/dsl.git
  80 .. _GPLv2: https://www.gnu.org/licenses/old-licenses/gpl-2.0.html
  81
  82 Contact
  83 -------
  84
  85 If you found a bug, or want to leave a comment, please
  86 `send me a mail <mailto:post-AT-ralfj-DOT-de>`_.