From 14cedf646361c0aee69fb33d44d1063bc80e1ee5 Mon Sep 17 00:00:00 2001 From: Ralf Jung Date: Sun, 10 Apr 2016 16:13:37 +0200 Subject: [PATCH] work on README --- README.md | 98 +++++++++++++++++++++++++++++++------------------------ 1 file changed, 55 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index 2512ae5..01ca101 100644 --- a/README.md +++ b/README.md @@ -5,75 +5,87 @@ This is the documentation of [LiLaSS]( https://www.ralfj.de/projects/lilass), a tool to setup screens on a Linux-powered Laptop. -LiLaSS is targeted for a specific use-case: The laptop is used both with the -internal screen only, and in combination with a single external screen. -[xrandr](http://www.x.org/wiki/Projects/XRandR) is used to detect whether an -external screen is plugged in, and to change the configuration according to the -user's specification. +LiLaSS is targeted for a specific use-case: The laptop is used both with the +internal screen only, and in combination with a single external screen. +[xrandr](http://www.x.org/wiki/Projects/XRandR) is used to detect whether an +external screen is plugged in, and to change the configuration according to the +user's specification. Furthermore, LiLaSS remembers the configuration used for +any particular screen, so that it can offer the same configuration next time. +You can even make it apply that configuration automatically. ## Usage -LiLaSS features an interactive and a batched mode of use. -Either way, if LiLaSS is started while no external screen is connected, it -enables the internal screen. +LiLaSS features an interactive and a batched mode of use. Either way, if LiLaSS +is started while no external screen is connected, it enables the internal +screen. It is in the case that an external screen is plugged in that the two modes differ. -Simply run `lilass` to start the interactive mode. A window will pop up, -allowing you to select which screens are enabled, their resolution, and how they -are positioned relatively to each other. The option `--frontend` (or `-f`) -can be used to choose the frontend which opens the window. Currently, the -frontends `qt` (using Qt5) and `zenity` are available. LiLaSS attempts to -choose an adequate frontend automatically. - -The option `--relative-position` (`-r`) suppresses the interactive -configuration. Instead, the given given option (`left`, `right`, `above`, -`below` or `mirror`) is applied with the default resolution of the external -screen. - -Finally, the flags `--internal-only` (`-i`) and `--external-only` (`-e`) -tells LiLaSS to use only one of the two screens. +Simply run `lilass` to start the interactive mode. A window will pop up, +allowing you to select which screens are enabled, their resolution, and how they +are positioned relatively to each other. The option `--frontend` (or `-f`) can +be used to choose the frontend which opens the window. Currently, the frontends +`qt` (using Qt5), `zenity` and `cli` are available. LiLaSS attempts to choose +an adequate frontend automatically. + +If a screen is connected that was already configured with LiLaSS before, the +previously selected configuration will be offered per default. You can pass +`--silent` (`-s`) to instead suppress the UI altogether, and just apply the +previous configuration. You can disable the use of the stored screen +configurations by passing `--no-db`. + +Furthermore, you can also suppress the UI in case LiLaSS sees a new screen by +telling LiLaSS directly what to do with that screen: With the flags +`--internal-only` (`-i`) and `--external-only` (`-e`), one of the two screens is +picked and the other one disabled. With `--relative-position` (`-r`), the +relative position of the two screens can be set (`left`, `right`, `above`, +`below` or `mirror`). In either case, the preferred possible resolution(s) of +the screen(s) will be picked if applicable. (In `mirror` mode, LiLaSS instead +picks the largest resolution that both screens have in common.) If the internal screen ends up being the only one that is used, LiLaSS attempts to turn on your backlight if it was disabled. ## Automatic Configuration -In combination with [x-on-resize](http://keithp.com/blogs/x-on-resize/) by Keith -Peckard, LiLaSS can automatically pop-up when a screen is plugged in, and -automatically re-enable the internal screen the external one is plugged off. +In combination with [x-on-resize](http://keithp.com/blogs/x-on-resize/) by Keith +Peckard, LiLaSS can be run automatically when a screen is plugged in, and +automatically re-enable the internal screen the external one is plugged off. As +LiLaSS remembers the screen configuration that was used last time, this +automatic mode will use the previous configuration if the same screen is +connected again. -Besides, you may want to apply some configuration without pop-up if an -external screen is plugged in when you log in to your desktop environment. +All this is achieved by running the following on log-in: -All this is achieved by running the following shell script on log-in: + x-on-resize --config "lilass -s -r mirror" --start - LILASS=/path/to/lilass - x-on-resize -c $LILASS - $LILASS --external-only +Of course, instead of `-r mirror`, you can pick a different default +configuration applied to screens that have not been seen previously. By dropping +this option altogether, LiLaSS will instead pop up and ask what to do when a new +screen is connected. ## Configuration File -You can use `~/.lilass.conf` to tell LiLaSS which are the names of your -internal and external connectors. These are the names as used by `xrandr`. The -option `internalConnector` gives the name of the xrandr connector -corresponding to your internal laptop screen. All the others will be considered -external screens, unless you use the option `externalConnectors` to provide a -(space-separated) list of connectors to be considered external by LiLaSS. Any +You can use `~/.config/lilass.conf` to tell LiLaSS which are the names of your +internal and external connectors. These are the names as used by `xrandr`. The +option `internalConnector` gives the name of the xrandr connector corresponding +to your internal laptop screen. All the others will be considered external +screens, unless you use the option `externalConnectors` to provide a +(space-separated) list of connectors to be considered external by LiLaSS. Any connector not mentioned in either option will be completely ignored. ## Source, License -You can find the sources in the [git -repository](http://www.ralfj.de/git/lilass.git) (also available [on -GitHub](https://github.com/RalfJung/lilass)). They are provided under the -[GPLv2](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html) or (at your -option) any later version of the GPL. See the file `LICENSE-GPL2` for more +You can find the sources in the +[git repository](http://www.ralfj.de/git/lilass.git) (also available +[on GitHub](https://github.com/RalfJung/lilass)). They are provided under the +[GPLv2](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html) or (at your +option) any later version of the GPL. See the file `LICENSE-GPL2` for more details. ## Contact If you found a bug, or want to leave a comment, please -[send me a mail](mailto:post-AT-ralfj-DOT-de). I'm also happy about pull +[send me a mail](mailto:post-AT-ralfj-DOT-de). I'm also happy about pull requests :) -- 2.30.2