Docs 30

README.md

@@ -1,7 +1,6 @@
 # Traditional T9 [![codebeat badge](https://codebeat.co/badges/f7ab222f-4c5d-4b79-b1c8-401eea79c206)](https://codebeat.co/projects/jackfan.us.kg-sspanak-tt9-master) ![GitHub Downloads (all assets, latest release)](https://img.shields.io/github/downloads/sspanak/tt9/latest/total)
 
-
-Traditional T9 (or TT9) is a T9 keyboard for devices with a hardware keypad. It supports predictive text typing in [20+ languages](app/languages/definitions), configurable hotkeys, and an on-screen keypad for touchscreen-only phones, bringing an old-school Nokia experience to modern Android devices. Best of all, it doesn't spy on you.
+A 12-key (T9) keyboard for devices with a hardware keypad. It supports predictive text typing in [20+ languages](app/languages/definitions), configurable hotkeys, and an on-screen keypad for touchscreen phones, bringing an old-school Nokia experience to modern Android devices. Best of all, it doesn't spy on you.
 
 This is a modernized version of the [original project](https://github.com/Clam-/TraditionalT9) by Clam-.
 
@@ -21,51 +20,60 @@ This is a modernized version of the [original project](https://github.com/Clam-/
     alt="Get it on GitHub"
     height="80">](https://github.com/sspanak/tt9/releases/latest)
 
+If your phone does not allow installing custom APKs, consult the [Installation Guide](docs/installation.md).
+
 ## ⚙️ System Requirements
 - Android 4.4 or higher. _(Tested and confirmed on Android 6, 10 and 11)_
 - A hardware keypad or a keyboard. For touchscreen-only devices, an on-screen keypad can be enabled in the Settings.
-- Minimum 58 Mb of storage space. Extra space is needed for language dictionaries in Predictive Mode.
+- Minimum 60 Mb of storage space. Extra space is needed for language dictionaries in Predictive Mode.
     - Very small languages (< 100k words; Yiddish, Indonesian): 5-6 Mb per language.
     - Small languages (100k-400k words; e.g. English, Norwegian, Swedish, Finnish, German, French): 15-30 Mb per language.
     - Medium languages (400k-800k words; e.g. Danish, Hebrew, Italian, Greek, Portuguese): 40-75 Mb per language
     - Large languages (800k-1.5M words; e.g. Arabic, Bulgarian, Spanish, Romanian, Ukrainian, Russian): 100-165 Mb per language
 
-_Storage usage depends on the word roots count, and the average word length in each language. Some languages will require more space, even if they have less words than others._
+_Storage usage depends on the word root count and the average word length in each language. Some languages will require more space, even if they have fewer words than others._
 
 ### ⚠️ Compatibility
 If you own a phone with Android 2.2 up to 4.4, please refer to the original version of Traditional T9 from 2016.
 
-TT9 may not work well on Kyocera phones, some Sonim phones and some other devices that run highly customized Android versions, where all apps are integrated and intended to work with the respective native keyboard. You may experience missing functionality or unexpected text/numbers appearing when you try to type.
+TT9 may not work well on Kyocera phones, Sonim phones running Android 10+, and some other devices that run highly customized Android versions, where all apps are integrated and intended to work with the respective native keyboard. You may experience missing functionality or unexpected text/numbers appearing when you try to type.
+
+Compatibility has been verified only on the following devices:
+- Unihertz Atom L (Android 11)
+- Qin F21 Pro+ (Android 11)
+- Energizer H620SEU (Android 10)
+- Sonim XP3800 (Android 8.1)
+- Vodaphone VFD 500 (Android 6.0)
 
 ## 🤔 How to Use Traditional T9?
-Before using Traditional T9 for the first time you need configure it and load a dictionary. After that, you can start typing right away in one of the three modes: Predictive, ABC or Numeric (123). And even if you have mastered the keypad back in the days, you will still find the Predictive mode now offers more powerful and smart new ways of typing with even less key presses.
+Before using Traditional T9 for the first time you need to configure it and load a dictionary. After that, you can start typing right away in one of the three modes: Predictive, ABC, or Numeric (123). And even if you have mastered the keypad back in the day, you will still find the Predictive mode now offers more powerful and smart new ways of typing with even fewer key presses.
 
-So make sure to read the initial setup and the hotkey tips in the [user manual](docs/user-manual.md). Also don't miss the convenient [compatibility options](docs/user-manual.md#compatibility-options--troubleshooting) aimed to improve the experience in some applications.
+So make sure to read the initial setup and the hotkey tips in the [user manual](docs/user-manual.md). Also, don't miss the convenient [compatibility options](docs/user-manual.md#compatibility-options--troubleshooting) aimed to improve the experience in some applications.
 
 ## ⌨ Contributing
 As with many other open-source projects, this one is also maintained by its author in his free time. Any help in making Traditional T9 better will be highly appreciated. Here is how:
 - Add [a new language](CONTRIBUTING.md#adding-a-new-language), [new UI translations](CONTRIBUTING.md#translating-the-ui) or simply fix a spelling mistake. The process is very simple and even with minimum technical knowledge, your skills as a native speaker will be of great use. Or, if you are not tech-savvy, just [open a new issue](https://github.com/sspanak/tt9/issues) and put the correct translations or words there. Correcting misspelled words or adding new ones is the best you can do to help. Processing millions of words in multiple languages is a very difficult task for a single person.
-- Share your list of added words. Use the Export function in: Settings → Languages → Added Words and upload the generated CSV file in a [new issue](https://github.com/sspanak/tt9/issues). You are also welcome to [open a PR](https://github.com/sspanak/tt9/pulls), if you have good technical knowledge and can split them by language.
-- [Report bugs](https://github.com/sspanak/tt9/issues) or other unusual behavior on different phones. Currently, the only testing and development devices are: Qin F21 Pro+ / Android 11; Energizer H620SEU / Android 10; Vodaphone VFD 500 / Android 6.0. But Android behaviour and appearance varies a lot across the millions of devices available out there.
-- Experienced developers who are willing fix a bug, or maybe create a brand new feature, see the [Contribution Guide](CONTRIBUTING.md).
+- Share your list of added words. Use the Export function in Settings → Languages → Added Words and upload the generated CSV file in a [new issue](https://github.com/sspanak/tt9/issues). You are also welcome to [open a PR](https://github.com/sspanak/tt9/pulls) if you have good technical knowledge and can split them by language.
+- [Report bugs](https://github.com/sspanak/tt9/issues) or other unusual behavior on different phones. It is only possible to verify correct operation and compatibility on [a handful of phones](#%EF%B8%8F-compatibility), but Android behavior and appearance vary a lot across the millions of devices available out there.
+- Experienced developers who are willing to fix a bug, or maybe create a brand new feature, see the [Contribution Guide](CONTRIBUTING.md).
 
 Your PRs are welcome!
 
 ## 👍 Support
 If you like Traditional T9, you could donate on [buymeacoffee.com](https://www.buymeacoffee.com/sspanak).
 
-Alternatively, you could donate a phone. This will make it easier to fix manufacturer-specific issues and test new features. Currently looking for: LG X100S, CAT S22 Flip, Sonim XP3 (any of: plus, non-plus, 38xx, 39xx), some Kyocera device. These are the most problematic of all and are hard to find where I live.
+Or if you just want to show your appreciation, give the project a star. Higher-ranked projects on GitHub have the opportunity to use development tools for free and apply for funding more easily.
 
-Or if you just want to show your appreciation, give the project a star. Higher ranked projects on GitHub have the opportunity to use development tools for free, and apply for funding easier.
+Thanks to your donations, a brand new testing device is available, a Sonim XP3800! This will result in much better compatibility with Sonim in the future. So, keep going!
 
 ## 🕮 License
-- The source code, the logo image and the icons are licensed under the conditions described in [LICENSE.txt](LICENSE.txt).
+- The source code, the logo image, and the icons are licensed under the conditions described in [LICENSE.txt](LICENSE.txt).
 - The dictionaries are licensed under the licenses provided in the [respective readme files](docs/dictionaries), where applicable. Detailed information about the dictionaries is also available there.
 - [Silver foil photo created by rawpixel.com - www.freepik.com](https://www.freepik.com/photos/silver-foil)
 - "Negotiate" and "Vibrocentric" fonts are under [The Fontspring Desktop/Ebook Font End User License](docs/desktop-ebook-EULA-1.8.txt).
 
 ## 💪 Privacy Policy and Philosophy
-- No ads.
+- No ads, no premium or paid features. It's all free.
 - No spying, no tracking, no telemetry or reports. No nothing!
 - No network connectivity.
 - It only does its job.

docs/installation.md

@@ -0,0 +1,57 @@
+# Traditional T9 Installation Guide
+
+## Devices that allow installing APKs
+
+### From F-Droid
+The recommended way of installing is using F-droid. It will automatically manage downloads and keep TT9 up-to-date. The downside is new versions may become available as late as two weeks after the official release.
+
+If you don't have F-droid, get the official F-droid APK from https://f-droid.org/ and install it. For more info, refer to the [installation instructions](https://f-droid.org/en/docs/Get_F-Droid/).
+
+After you get F-droid working, just open it, search for "Traditional T9" and install it.
+
+### From GitHub
+If you would like to run the latest version as soon as it is released, go to the GitHub [Releases section](https://github.com/sspanak/tt9/releases). Then either download the APK on your phone or download it on a computer and transfer it to the phone. After that, just click or tap to install. If custom APK installation is enabled, it will just work. If not, your phone may show a popup, asking you to grant the installation permission, before proceeding.
+
+In some cases, installation permissions are disabled by default, but you can usually enable them by going to Android Settings → Apps → Settings → Security, then enabling "Installation from unknown sources".
+
+_The setting name or location may be different on different Android versions. Nevertheless, a quick Google search for your phone make and model, should point you in the right direction._
+
+## Devices that do not allow installing APKs or do not display TT9 after installation
+Some manufacturers prefer to lock their devices and disallow installing or enabling (or both) third-party keyboards or apps in general. It is likely to reduce the complaints "my phone isn't working", caused by the manually installed apps. The problem has been discussed [here](https://github.com/sspanak/tt9/issues/455) and [here](https://github.com/sspanak/tt9/issues/198).
+
+Examples of such phones include some Kyocera models, for example, the DuraXV Extreme+, ZMI Z1, all models by Sonim, and so on. On Sonim XP3800 and XP5800, there is an "Install from Unknown Sources" option, but since the November 2022 update, the phone will still refuse to install APKs unless they have been sent to and approved by Sonim.
+
+### Prepare Your Computer
+To install TT9 on such locked devices, you will have to connect your phone to a computer and use a program called "adb" (Android Debug Bridge). If you feel confident using the command line, follow the instructions below.
+
+First, go through the [adb quick setup](https://www.xda-developers.com/install-adb-windows-macos-linux/). If you need more detailed info, see the [developer documentation](https://developer.android.com/tools/adb).
+
+### Prepare the Phone
+If you have successfully enabled the Developer Mode while setting up ADB, proceed to the next step.
+
+On older phones, the Developer Mode cannot be enabled by clicking the build number. Instead, it is done by dialing a special code which usually looks like this: `*#*#XXXX#*#*`, where XXXX is some number. Find the code for your phone and dial it. Usually, phones from the same company, running the same Android version, share the same code. For example, the code for Sonim XP3800 also works on XP5800.
+
+_The procedure on your phone may be entirely different from the methods described above, but Google is your friend. It should be fairly easy to find how to do it unless your phone is completely locked._
+
+### Install
+If your phone permits installing APKs, skip this step and install normally. Otherwise, install using:
+
+```bash
+adb install /path/to/apk/on/your/computer/tt9-vXXX.apk
+```
+
+_If you are installing over a previously installed version, you may have to uninstall the old one first. See below._
+
+### Enable
+
+```bash
+adb shell ime enable io.github.sspanak.tt9/.ime.TraditionalT9
+```
+
+_That's it! TT9 should appear the next you start typing._
+
+### Uninstall
+
+```bash
+adb shell pm uninstall io.github.sspanak.tt9
+```