From e9e7991ee653c4797979fb1d3e88b5043f97fe8f Mon Sep 17 00:00:00 2001
From: bdeshi <bdeshi@bdeshi.space>
Date: Thu, 22 Aug 2024 03:44:03 +0600
Subject: [PATCH] update-readme (#1)

- add brew commands (using custom taps)
- add usage section
- remove confusing notes section
- fix markdown linting issues
- re-order sections
- minor phrasing and wording adjustments

Reviewed-on: https://git.bdeshi.space/bdeshi/probhat-mac-osx/pulls/1
---
 README.md | 71 +++++++++++++++++++++++++++++++++++++------------------
 1 file changed, 48 insertions(+), 23 deletions(-)

diff --git a/README.md b/README.md
index 1667a05..1f9f83a 100644
--- a/README.md
+++ b/README.md
@@ -1,41 +1,66 @@
-### Probhat Bangla keyboard layout for Mac OSX
+# Probhat Keyboard Layout for Mac OSX
 
-This project hosts Probhat keyboard layout configuration for Mac OSX systems.
+This project provides the Probhat keyboard layout as a Mac OS native bundle. Probhat is one of the most popular keyboard layouts for the Bangla (aka Bengali) language.
+
+This is faithful to the scheme published at [ekushey.org][e] <sup>[🏛][w]</sup> with two variations:
 
-There are two variations:
 - **Probhat (BD)**: BDT symbol (৳) on <kbd>SHIFT</kbd>+<kbd>4</kbd>
 - **Probhat (IN)**: INR symbol (₹) on <kbd>SHIFT</kbd>+<kbd>4</kbd>
 
-Other than this variation, the layouts are faithful to the scheme published at [ekushey.org][e]<span style="font-size:60%">[🏛][w]</span>
+⭐ *if this is useful to you, feel free to add a github star, thanks!* ⭐
 
-### INSTALLATION
-#### install for current user
-Copy [`ProbhatKeyboardLayout.bundle`][p] to `~/Library/Keyboard Layouts/`
+## Install
 
-#### install system-wide
-Copy [`ProbhatKeyboardLayout.bundle`][p] to `/Library/Keyboard Layouts/`
+### With Homebrew
 
-#### uninstall
-Remove `ProbhatKeyboardLayout.bundle` from where ever you'd copied it to.
+Run this command to install:
 
-![graphical view of the layout](./probhat-layout-apple-wireless.png)
-<sup>(image generated with https://keyboard-layout-editor.com)</sup>
+```sh
+brew install --cask bdeshi/taps/probhat-keyboard-layout
+```
 
-### NOTES
-- The <kbd>Control</kbd> and <kbd>Command</kbd> special keys use US QWERTY layouts.
-- Some key combinations may conflict with some application-specific shortcuts. For example, <kbd>SHIFT</kbd>+<kbd>ALT</kbd>+<kbd>A</kbd> toggles block comments by default in VSCode.
+and this one to uninstall:
 
-### ISSUES
-Please [report issues or missing features][s]!
+```sh
+brew uninstall --cask bdeshi/taps/probhat-keyboard-layout
+```
 
-### CREDITS
-The Probhat layout was developed by Ankurbangla.org.
-This layout bundle was generated with the help of [Ukelele][k] and no guitars.
+### Without Homebrew
+
+Download and open a **source archive** of this project from the [Releases][r] page, and copy [`ProbhatKeyboardLayout.bundle`][p] to `~/Library/Keyboard Layouts/` (`~` means your home folder).
+
+To uninstall, remove `ProbhatKeyboardLayout.bundle` from `~/Library/Keyboard Layouts/`.
+
+## Usage
+
+*These directions may differ slightly across Mac OS versions.*
+
+Go to **System Settings > Keyboard**, add Probhat (BD) or Probhat (IN) in the **Input Sources** section.
+
+Find or set the keyboard shortcut for cycling layouts in **System Settings > Keyboard > Keyboard Shortcuts > Input Sources**.
+
+Layouts can be cycled from the menu bar as well by enabling the input menu item.
+
+## Issues
+
+Please report issues or feature requests on [github][s1] (or [gitea][s2]).
+
+## Credits
+
+- The Probhat layout was developed by ankurbangla.org.
+- This Mac OS native keyboard layout bundle was generated with [Ukelele][k] (no guitars, sorry).
 
 <hr>
 
+## The Keyboard Layout
+
+![graphical view of the layout](./probhat-layout-apple-wireless.png)
+<sup>image generated with https://keyboard-layout-editor.com</sup>
+
 [e]: https://www.ekushey.org/?page/probhat_layout
 [w]: https://web.archive.org/web/20200815053905/https://ekushey.org/?page/probhat_layout
+[r]: /bdeshi/probhat-mac-osx/releases
 [p]: ProbhatKeyboardLayout.bundle
-[s]: https://github.com/bdeshi/probhat-mac-osx/issues
-[k]: https://software.sil.org/ukelele/
\ No newline at end of file
+[s1]: https://github.com/bdeshi/probhat-mac-osx/issues
+[s2]: https://git.bdeshi.space/bdeshi/probhat-mac-osx/issues
+[k]: https://software.sil.org/ukelele/