README.md

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