Skip to content

Commit

Permalink
doc: refactor docs
Browse files Browse the repository at this point in the history 
fix markdown
update some parts

Co-authored-by: Christian Krieg <christian@drkrieg.at>
  • Loading branch information
@Barabazs @christian-krieg
Barabazs and christian-krieg committed Mar 4, 2023
1 parent 9b7611a commit 06aec6e
Show file tree
Hide file tree
Showing 2 changed files with 36 additions and 44 deletions.
35 changes: 16 additions & 19 deletions README.md
View file
Expand Up @@ -12,35 +12,32 @@ Hence, I’m looking for maintainers (developers) to continue work on this proje
In meantime, I’ll devote the bare minimum of my time which will mostly consist of MR (merge requests) code review and approval.
-->

#### Why do I need displaylink-debian?
## Why do I need displaylink-debian?

[DisplayLink][] releases its drivers only for Ubuntu xx.04 LTS. Hence if you run any other Ubuntu version or any other Linux distribution DisplayLink will not work as expected.

[displaylink-debian][] allows seamless installation of the official
DisplayLink drivers tailored to work for most of the Debian based Linux distributions regardless of which Linux kernel version (>4.15) you're using.

#### How to run "displaylink-debian"
## Installation
1. Download the repo, cd in the directory and run the shell script with sudo:
```shell
git clone https://github.com/AdnanHodzic/displaylink-debian.git
cd displaylink-debian
sudo ./displaylink-debian.sh
```
1. Then consult the [Post Install Guide][PostInstall] to make sure everything works as intended.

##### Repo clone

`sudo apt-get install git`

`git clone https://github.com/AdnanHodzic/displaylink-debian.git`

`cd displaylink-debian/ && sudo ./displaylink-debian.sh`

*After installation has been completed, make sure to consult [Post Install Guide][PostInstall]!*


#### Post installation Guide and Troubleshooting
## Troubleshooting and debugging

***Please note:** Your external monitor/s may not work as expected unless you perform additional steps as described in the [Post Installation Guide][PostInstall].*

Before submitting a bug report in the [issue tracker](https://github.com/AdnanHodzic/displaylink-debian/issues/new), please make sure to:
* read [Troubleshooting most common issues][TroubleShooting].
* when submitting a new issue, include debug information by running: `sudo ./displaylink-debian.sh --debug`

#### Supported platforms are:
## Supported platforms are:

* Debian: Jessie 8.0/Stretch 9.0/Buster 10/Bullseye 11/Bookworm (testing)/Sid (unstable)
* Ubuntu: 14.04 Trusty - 22.04 Jammy
Expand All @@ -63,7 +60,7 @@ Before submitting a bug report in the [issue tracker](https://github.com/AdnanHo

If your distribution or version is not on the list, make sure to include debug information by running: `sudo ./displaylink-debian.sh --debug` and [submit a request to add support for it](https://github.com/AdnanHodzic/displaylink-debian/issues/new).

#### Technical
## Technical

* _displaylink-debian.sh_ downloads and extracts the contents of the
official [DisplayLink Ubuntu driver][upstream].
Expand All @@ -74,7 +71,7 @@ Before submitting a bug report in the [issue tracker](https://github.com/AdnanHo
* Install/Reinstall/Uninstall is performed.


#### Discussion
## Discussion

* [Kernel agnostic, DisplayLink Debian GNU/Linux driver installer][blog]

Expand All @@ -86,14 +83,14 @@ Before submitting a bug report in the [issue tracker](https://github.com/AdnanHo
[PostInstall]: https://github.com/AdnanHodzic/displaylink-debian/blob/master/post-install-guide.md
[TroubleShooting]: https://github.com/AdnanHodzic/displaylink-debian/blob/master/post-install-guide.md#troubleshooting-most-common-issues

#### Donate (PayPal or Bitcoin)
## Donate (PayPal or Bitcoin)

Since I'm working on this project in free time without any support or reimbursement from DisplayLink, and [have saved some 100$](https://github.com/AdnanHodzic/displaylink-debian/issues/172#issuecomment-441384936). Please consider supporting this project by making a donation of any amount!

##### PayPal
### PayPal
[![paypal](https://www.paypalobjects.com/en_US/NL/i/btn/btn_donateCC_LG.gif)](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=adnan%40hodzic.org&item_name=Contribution+for+work+on+debian-displaylink&currency_code=EUR&source=url)

##### BitCoin
### BitCoin
[bc1qlncmgdjyqy8pe4gad4k2s6xtyr8f2r3ehrnl87](bitcoin:bc1qlncmgdjyqy8pe4gad4k2s6xtyr8f2r3ehrnl87)

[![bitcoin](https://foolcontrol.org/wp-content/uploads/2019/08/btc-donate-displaylink-debian.png)](bitcoin:bc1qlncmgdjyqy8pe4gad4k2s6xtyr8f2r3ehrnl87)
45 changes: 20 additions & 25 deletions post-install-guide.md
View file
@@ -1,18 +1,7 @@
# Post Installation Guide

* [Prerequisites](#prerequisites)

* [Display detection](#display-detection)

* [Screen Layout Configuration](#screen-layout-configuration)

* [Automated (persistent) display configuration](#automated-persistent-display-configuration)

* [Troubleshooting most common issues](#troubleshooting-most-common-issues)

* [Having a different problem](#having-a-different-problem)

### Prerequisites
## Prerequisites

* Make sure that UEFI/secure boot is disabled!

Expand Down Expand Up @@ -44,7 +33,7 @@ If you have Nvidia or ATI/AMD graphics card, try removing: `/etc/X11/xorg.conf.d

If none of the suggestions in [Prerequsites section](https://github.com/AdnanHodzic/displaylink-debian/blob/master/post-install-guide.md#prerequisites) solved your problem, make sure to consult [Troubleshooting most common issues](https://github.com/AdnanHodzic/displaylink-debian/blob/master/post-install-guide.md#troubleshooting-most-common-issues).

### Display Detection
## Display Detection

Only do this in case your monitors weren't automatically detected.

Expand Down Expand Up @@ -83,11 +72,11 @@ Provider 4: id: 0xd2 cap: 0x2, Sink Output crtcs: 1 outputs: 1 associated provid
For further reference I suggest reading:
[How to use xrandr](https://web.archive.org/web/20180224075928/https://pkg-xorg.alioth.debian.org/howto/use-xrandr.html)

### Screen Layout Configuration
## Screen Layout Configuration

There are couple of tools to help you configure screen layout of your external monitors.

##### xrandr
### xrandr

Depending on your setup, to place DVI-1-0 virtually-right of the eDP1 display you'd run:

Expand All @@ -96,31 +85,31 @@ Depending on your setup, to place DVI-1-0 virtually-right of the eDP1 display yo
For further reference I suggest reading:
[How to use xrandr](https://web.archive.org/web/20180224075928/https://pkg-xorg.alioth.debian.org/howto/use-xrandr.html)

##### GNOME Displays
### GNOME Displays

If you're GNOME desktop user, simply run:

```gnome-control-center display```

##### arandr
### arandr

Another very easy and intuative (gui) tool is ```arandr``` (Another XRandR GUI)

Make sure to install it first: ```sudo apt-get install arandr```

### Automated (persistent) display configuration
## Automated (persistent) display configuration

Since hotplug doesn't work (on Debian and Kali) and every time you connect your computer to Displaylink you'll need to re-configure your displays.

I've set-up couple of [aliases](http://www.linfo.org/alias.html) which help me accomplish this in semi-automated manner.

Every time I connect my computer to DisplayLink ...

##### two
### two

I simple run ```two``` which is an alias for setting up two external displays as primary and secondary, whilst turning off laptop built in display. So I can close the lid.

##### one
### one

Every time I want to diconnect my displays I run ```one```. Which turns off both external displays, turns on built in laptop display and makes it a primary (default behaviour).

Expand All @@ -136,7 +125,13 @@ alias one="xrandr --output VIRTUAL1 --off --output DVI-1-0 --off --output DP1 --

Note, in case you're editting ```~/.bashrc```, make sure you run ```source ~/.bashrc``` to appy the changes without having to log in/out.

### Troubleshooting most common issues
## Upgrading your OS or updating displaylink
It's recommended to run the uninstall and install procedure separately instead of relying on the reinstall option.
1. `sudo ./displaylink-debian.sh --uninstall`
2. reboot
3. `sudo ./displaylink-debian.sh --install`

## Troubleshooting most common issues

* [Disable UEFI / secure boot](https://github.com/AdnanHodzic/displaylink-debian/issues/123)

Expand All @@ -154,12 +149,12 @@ Note, in case you're editting ```~/.bashrc```, make sure you run ```source ~/.ba

* [`Can't open display :0` error](https://github.com/AdnanHodzic/displaylink-debian/issues/639)

##### Monitoring for errors
### Monitoring for errors

* Monitor ```dmesg | grep Display``` output while plugging in Displaylink
* Monitor ```/var/log/displaylink/DisplayLinkManager.log``` file

##### Most common Debian Jessie related issues:
### Most common Debian Jessie related issues:
* systemctl status dlm.service failure
* Glibc GLIBCXX_3.4.21 missing

Expand All @@ -171,7 +166,7 @@ Should you experience problems with the display either remaining black, only sho

Reference: [issue #68](https://github.com/AdnanHodzic/displaylink-debian/issues/68)

##### syntax error near unexpected token \`newline'...
### syntax error near unexpected token \`newline'...

If you just downloaded the script and tried to execute it, you might get the following error:

Expand Down Expand Up @@ -207,6 +202,6 @@ References: [issue #111](https://github.com/AdnanHodzic/displaylink-debian/issue
[issue #65](https://github.com/AdnanHodzic/displaylink-debian/issues/65)


### Having a different problem?
## Having a different problem?

When submitting a new [issue](https://github.com/AdnanHodzic/displaylink-debian/issues), include debug information by running: `sudo ./displaylink-debian.sh --debug`

0 comments on commit 06aec6e

Please sign in to comment.