README.rst

   1 LiLaSS - Linux Laptop Screen Setup
   2 ==================================
   3
   4 Introduction
   5 ------------
   6
   7 This is the documentation of LiLaSS_, a tool to setup screens on a Linux-powered
   8 Laptop.
   9
  10 LiLaSS 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 .. _LiLaSS: https://www.ralfj.de/projects/lilass
  16 .. _xrandr: http://www.x.org/wiki/Projects/XRandR
  17
  18 Usage
  19 -----
  20
  21 LiLaSS features an interactive and a batched mode of use.
  22 Either way, if LiLaSS is started while no external screen is connected, it
  23 enables the internal screen.
  24
  25 It is in the case that an external screen is plugged in that the two modes
  26 differ.
  27
  28 Simply run ``lilass`` to start the interactive mode. A window will pop up,
  29 allowing you to select which screens are enabled, their resolution, and how they
  30 are positioned relatively to each other. The option ``--frontend`` (or ``-f``)
  31 can be used to choose the frontend which opens the window. Currently, the
  32 frontends ``qt`` and ``zenity`` are available. LiLaSS attempts to choose an
  33 adequate frontend automatically.
  34
  35 The option ``--relative-position`` (``-r``) suppresses the interactive
  36 configuration. Instead, the given given option (``left``, ``right``, ``above``,
  37 ``below`` or ``mirror``) is applied with the default resolution of the external
  38 screen.
  39
  40 Finally, the flags ``--internal-only`` (``-i``) and ``--external-only`` (``-e``)
  41 tells LiLaSS to use only one of the two screens.
  42
  43 If the internal screen ends up being the only one that is used, LiLaSS attempts
  44 to turn on your backlight if it was disabled.
  45
  46 Automatic Configuration
  47 -----------------------
  48
  49 In combination with x-on-resize_ by Keith Peckard, LiLaSS can automatically
  50 pop-up when a screen is plugged in, and automatically re-enable the internal
  51 screen the external one is plugged off.
  52
  53 Besides, you may want to apply some configuration without pop-up if an
  54 external screen is plugged in when you log in to your desktop environment.
  55
  56 All this is achieved by running the following shell script on log-in::
  57
  58   LILASS=/path/to/lilass
  59   x-on-resize -c $LILASS
  60   $LILASS --external-only
  61
  62 .. _x-on-resize: http://keithp.com/blogs/x-on-resize/
  63
  64 Configuration File
  65 ------------------
  66
  67 You can use ``~/.lilass.conf`` to tell LiLaSS which are the names of your
  68 internal and external connectors. These are the names as used by ``xrandr``. The
  69 option ``internalConnector`` gives the name of the xrandr connector
  70 corresponding to your internal laptop screen. All the others will be considered
  71 external screens, unless you use the option ``externalConnectors`` to prove a
  72 (space-separated) list of connectors to be considered external by LiLaSS. Any
  73 connector not mentioned in either option will be completely ignored.
  74
  75 Source, License
  76 ---------------
  77
  78 You can find the sources in the `git repository`_ (also available `on GitHub`_).
  79 They are provided under the GPLv2_ or (at your option) any later version of the
  80 GPL. See the file ``LICENSE-GPL2`` for more details.
  81
  82 .. _git repository: http://www.ralfj.de/git/lilass.git
  83 .. _on GitHub: https://github.com/RalfJung/lilass
  84 .. _GPLv2: https://www.gnu.org/licenses/old-licenses/gpl-2.0.html
  85
  86 Contact
  87 -------
  88
  89 If you found a bug, or want to leave a comment, please
  90 `send me a mail <mailto:post-AT-ralfj-DOT-de>`_. I'm also happy about pull
  91 requests :)