fix documentation
[lilass.git] / 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`_ and `on GitHub`_. They are
79 provided under the GPLv2_ or (at your option) any later version of the GPL.
80
81 .. _git repository: http://www.ralfj.de/git/lilass.git
82 .. _on GitHub: https://github.com/RalfJung/lilass
83 .. _GPLv2: https://www.gnu.org/licenses/old-licenses/gpl-2.0.html
84
85 Contact
86 -------
87
88 If you found a bug, or want to leave a comment, please
89 `send me a mail <mailto:post-AT-ralfj-DOT-de>`_. I'm also happy about pull
90 requests :)