From 9017fadba6d940095a36e59d0ca4c053dfa77e85 Mon Sep 17 00:00:00 2001
From: Takase <20792268+takase1121@users.noreply.github.com>
Date: Thu, 12 Oct 2023 00:24:42 +0800
Subject: [PATCH] docs: fix prebuilt install instructions (#1637)

* docs: fix prebuilt install instructions

Added missing documentation for Windows and macOS.
Also updated the Linux instruction for creating desktop entries.

* docs: more clarification and grammar fixes

* docs: clarify plugin and config load in portable mode

* docs: better phrasing

Co-authored-by: Guldoman <giulio.lettieri@gmail.com>

* docs: better phrasing

Co-authored-by: Guldoman <giulio.lettieri@gmail.com>

---------

Co-authored-by: Guldoman <giulio.lettieri@gmail.com>
---
 README.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 65 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index c6b21e85..0bd00e48 100644
--- a/README.md
+++ b/README.md
@@ -81,6 +81,29 @@ affects only the place where the application is actually installed.
 
 Head over to [releases](https://github.com/lite-xl/lite-xl/releases) and download the version for your operating system.
 
+### Windows
+
+Lite XL comes with installers on Windows for typical installations.
+Alternatively, we provide ZIP archives that you can download and extract anywhere and run directly.
+
+To make Lite XL portable (e.g. running Lite XL from a thumb drive),
+simply create a `user` folder where `lite-xl.exe` is located.
+Lite XL will load and store all your configurations and plugins in the folder.
+
+### macOS
+
+We provide DMG files for macOS. Simply drag the program into your Applications folder.
+
+> **Important**
+> Since Lite XL is not signed, you **must** run this command before starting Lite XL:
+> 
+> ```sh
+> # clears attributes from the directory
+> xattr -cr /Applications/Lite\ XL.app
+> ```
+>
+> Otherwise, macOS will display a **very misleading error** saying that the application is damaged.
+
 ### Linux
 
 Unzip the file and `cd` into the `lite-xl` directory:
@@ -91,6 +114,7 @@ cd lite-xl
 ```
 
 To run lite-xl without installing:
+
 ```sh
 ./lite-xl
 ```
@@ -103,21 +127,59 @@ mkdir -p $HOME/.local/bin && cp lite-xl $HOME/.local/bin/
 mkdir -p $HOME/.local/share/lite-xl && cp -r data/* $HOME/.local/share/lite-xl/
 ```
 
+#### Add Lite XL to PATH
+
+To run Lite XL from the command line, you must add it to PATH.
+
 If `$HOME/.local/bin` is not in PATH:
 
 ```sh
 echo -e 'export PATH=$PATH:$HOME/.local/bin' >> $HOME/.bashrc
 ```
 
-To get the icon to show up in app launcher:
+Alternatively on recent versions of GNOME and KDE Plasma,
+you can add `$HOME/.local/bin` to PATH via `~/.config/environment.d/envvars.conf`:
+
+```ini
+PATH=$HOME/.local/bin:$PATH
+```
+
+> **Note**
+> Some systems might not load `.bashrc` when logging in.
+> This can cause problems with launching applications from the desktop / menu.
+
+#### Add Lite XL to application launchers
+
+To get the icon to show up in app launcher, you need to create a desktop
+entry and put it into `/usr/share/applications` or `~/.local/share/applications`.
+
+Here is an example for a desktop entry in `~/.local/share/applications/com.lite_xl.LiteXL.desktop`,
+assuming Lite XL is in PATH:
+
+```ini
+[Desktop Entry]
+Type=Application
+Name=Lite XL
+Comment=A lightweight text editor written in Lua
+Exec=lite-xl %F
+Icon=lite-xl
+Terminal=false
+StartupWMClass=lite-xl
+Categories=Development;IDE;
+MimeType=text/plain;inode/directory;
+```
+
+To get the icon to show up in app launcher immediately, run:
 
 ```sh
 xdg-desktop-menu forceupdate
 ```
 
-You may need to logout and login again to see icon in app launcher.
+Alternatively, you may log out and log in again.
 
-To uninstall just run:
+#### Uninstall
+
+To uninstall Lite XL, run:
 
 ```sh
 rm -f $HOME/.local/bin/lite-xl
@@ -127,7 +189,6 @@ rm -rf $HOME/.local/share/icons/hicolor/scalable/apps/lite-xl.svg \
           $HOME/.local/share/lite-xl
 ```
 
-
 ## Contributing
 
 Any additional functionality that can be added through a plugin should be done