s3rius/squeekboard
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

documentation: Improve documentation

Browse Source 
Part-of: <https://gitlab.gnome.org/World/Phosh/squeekboard/-/merge_requests/662>
This commit is contained in:
MoonlightWave-12
2024-08-16 12:02:17 +02:00
committed by Marge Bot
parent d67653abdf
commit 0adbc40426
5 changed files with 97 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
README.md
View File

@ -1,7 +1,7 @@
*squeekboard* - a Wayland on-screen keyboard
========================================
*Squeekboard* is the on-screen keyboard for Phosh. It is primarily designed for smartphones, tablet-PCs, and other devices with touchscreens.
*Squeekboard* is the on-screen-keyboard input-method for Phosh. It is primarily designed for smartphones, tablet-PCs, and other devices with touchscreens.
It squeaks because some Rust got inside.
@ -30,6 +30,12 @@ Creating layouts
If you want to work on layouts, check out the [guide](doc/tutorial.md).
Nightly builds
--------------
For testing the latest commits of the `main`-branch, one can install the nightly builds of Squeekboard.
For more information about the nightly builds, read the ["Phosh Nightly Package Builds"-blog-post](https://phosh.mobi/posts/phosh-nightly/).
Building
--------
@ -43,7 +49,7 @@ See `.gitlab-ci.yml` or run `apt-get build-dep .`
$ git clone https://gitlab.gnome.org/World/Phosh/squeekboard.git
$ cd squeekboard
$ mkdir _build
$ meson _build/
$ meson setup _build/
$ cd _build
$ ninja
```
@ -54,10 +60,14 @@ Running
-------
```sh
$ phoc # if no compatible Wayland compositor is running yet
$ cd ../build/
$ src/squeekboard
```
If no compatible Wayland compositor is running yet, you can use Phoc (after installing it):
```sh
$ phoc --exec 'src/squeekboard'
```
Squeekboard's panel will appear whenever a compatible application requests an input method. Click a text field in any GTK application, like `python3 ./tools/entry.py`.
@ -72,6 +82,7 @@ Alternatively, force panel visibility manually with:
```sh
$ busctl call --user sm.puri.OSK0 /sm/puri/OSK0 sm.puri.OSK0 SetVisible b true
```
or by using the environment-variable `SQUEEKBOARD_DEBUG=force_show`.
### What the compositor has to support

61
doc/hacking.md
View File

@ -45,8 +45,6 @@ Development environment
*Squeekboard* is regularly built and tested on [Debian Testing](https://www.debian.org/releases/testing/) and [Mobian Testing](https://mobian.org/).
For testing Squeekboard on a PC as if it was used on a smartphone, one can use an emulator. Instructions for that can be found in the [documentation for setting up a development-environment for the Librem 5](https://developer.puri.sm/Librem5/Development_Environment/Boards/emulators.html).
### Dependencies
On a Debian based system run
@ -58,22 +56,69 @@ $ sudo apt-get -y build-dep .
For an explicit list of dependencies check the `Build-Depends` entry in the [`debian/control`](debian/control) file.
### Building Squeekboard
```sh
$ meson setup _build
$ ninja -C _build
```
### Some recommended software for development
- [rust-analyzer](https://rust-analyzer.github.io/) - Can offer additional information about code in an IDE (for example: in GNOME Builder).
- [phoc](https://gitlab.gnome.org/World/Phosh/phoc) - To run Squeekboard in a [nested session](https://phosh.mobi/posts/phosh-dev-part-0/) (for example: while in a GNOME session).
For testing Squeekboard on a PC as if it was used on a smartphone, one can also use an emulator. Instructions for that can be found in the [documentation for setting up a development-environment for the Librem 5](https://developer.puri.sm/Librem5/Development_Environment/Boards/emulators.html).
Testing
-------
Most common testing is done in CI. Occasionally, and for each release, do perform manual tests to make sure that
Most common testing is done in CI. Occasionally, and for each release, do perform manual tests to make sure that:
- the application draws correctly
- it shows when relevant
- it changes layouts
- it changes views
#### Setting up for manual testing
While one can simply use a computer which uses Squeekboard already, it may be necessary to restart the session for actually testing the changes.
A more convenient way, is to use Phoc to run Squeekboard in a nested session ([more information](https://phosh.mobi/posts/phosh-dev-part-0/)), while in another session (for example: GNOME, or KDE Plasma):
First, install Phoc, either with `sudo apt install phoc` (on Debian-based distributions), or from the [source-code](https://gitlab.gnome.org/World/Phosh/phoc).
Then prepare a config-file (`phoc.ini`) for Phoc, to ensure that Squeekboard will be shown how it would be shown on an actual device (though, the size of the window will probably be different than the size of the display).
Example of a `phoc.ini` matching the PinePhone Pro:
```ini
[output:WL-1]
# Resolution in px. Swap the values to change between vertical or horizontal orientation.
mode = 720x1440
# Width and height in mm.
phys_width = 68
phys_height = 136
```
Then (after Squeekboard has been built) use a command like the following, to start `phoc` together with Squeekboard:
```sh
$ SQUEEKBOARD_DEBUG=force_show GTK_THEME=Adwaita:dark phoc --config 'path-to/phoc.ini' --exec '_build/src/squeekboard'
```
You can move the window of Phoc, by pressing down the Super-key while clicking and dragging the window.
It can also be set to be always on top, by pressing the Super-key, doing a right-click on the window, and then selecting the option for that.
#### Testing with an application
```sh
$ python3 tools/entry.py
```
To test an application with Squeekboard in a nested session, one can use the environment-variable `WAYLAND_DISPLAY`, to open the application in that session. For example:
```sh
$ WAYLAND_DISPLAY=wayland-1 python3 tools/entry.py
```
#### Testing visibility
```sh
@ -88,7 +133,7 @@ Available Layouts can be selected by using the GNOME Settings application.
Those can also be set with `gsettings`:
```sh
# define all available layouts. First one is currently selected.
# Define all available layouts. First one is currently selected.
$ gsettings set org.gnome.desktop.input-sources sources "[('xkb', 'us'), ('xkb', 'de')]"
```
@ -219,20 +264,18 @@ $ sh /source_path/cargo.sh test
All Cargo dependencies must be selected in the version available in Debian Testing, and added to the file `debian/control`. Please check with the [Debian package search](https://www.debian.org/distrib/packages).
Dependencies must be specified in `Cargo.toml` with 2 numbers: "major.minor". Since bugfix version number is meant to not affect the interface, this allows for safe updates.
Dependencies must be specified in `Cargo.toml` with 2 numbers: "major.minor". Since the bugfix version number is meant to not affect the interface, this allows for safe updates.
Releases
--------
Feature-releases should me made in time for new [Phosh releases](https://gitlab.gnome.org/World/Phosh/phosh/-/wikis/Releases) (which is currently about once a month), so that the release-notes can contain the news about Squeekboard.
Feature-releases should me made in time for new [Phosh releases](https://gitlab.gnome.org/World/Phosh/phosh/-/wikis/Releases) (which is currently about once in one and a half months), so that the release-notes can contain the news about Squeekboard.
However, it is not necessary to make a new release of Squeekboard for every release of Phosh.
Bug-fix-releases should be made more often, preferably directly after important bug-fixes have been made.
### 1. Update `Cargo.lock`
While the file is not actually used, it's a good idea to save the config in case some rare bug appears in dependencies.
```sh
$ cd squeekboard-build
$ .../squeekboard-source/cargo.sh update
@ -275,7 +318,7 @@ Add the updated `debian/changelog` to the commit. The commit message should cont
Summarize the changes since the last release in the NEWS file. Use the Markdown syntax, e.g.
```
1.22.0 "Superposition"
squeekboard 1.22.0 "Superposition"
-----------------------------
Changes:

4
doc/index.md
View File

@ -4,7 +4,7 @@ Welcome to squeekboard's documentation!
Introduction
------------
*Squeekboard* is the on-screen keyboard for Phosh. It is primarily designed for smartphones, tablet-PCs, and other devices with touchscreens.
*Squeekboard* is the on-screen-keyboard input-method for Phosh. It is primarily designed for smartphones, tablet-PCs, and other devices with touchscreens.
Building
--------
@ -14,7 +14,7 @@ For information about building Squeekboard, read the [README](README.md).
Layouts
-------
Squeekboard can [load user-provided keyboard-layouts](layouts.md#using-custom-layouts). Those can be created and used without recompiling the keyboard code. The [tutorial](tutorial.md) explains the process in detail.
Squeekboard can [load user-provided keyboard-layouts](layouts.md). Those can be created and used without recompiling the keyboard code. The [tutorial](tutorial.md) explains the process in detail.
Layouts are created using a [text-based format, based on YAML](layouts.md).

27
doc/layouts.md
View File

@ -3,7 +3,9 @@ Layouts
Squeekboard is composed of multiple layouts, several for each language, multiplied by each hint.
Layouts live in the "keyboards" directory.
The available layouts are in the "data/keyboards/" directory.
For creating new layouts, reading the [tutorial](tutorial.md) can be useful.
Hints
-----
@ -41,6 +43,29 @@ Layout-size
- Basic/compact shape: 12:7
- Wide shape: 16:5
### Recommended settings for creating layouts while using Phoc
For testing the basic/compact shape:
```sh
[output:WL-1]
mode = 360x720
```
For testing the wide shape:
```sh
[output:WL-1]
mode = 1280x800
```
Make sure there is no `phys_height` or `phys_width` set.
### Layout-stretching
Squeekboard may slightly stretch layouts horizontally (up to 5.5%) before showing them.
For creating layouts with precise sizes, it can be useful to disable this.
This can be done by changing the value `1.055` in the line `let scale_x = if (h_scale / v_scale) < 1.055 { h_scale } else { v_scale };` of the `calculate_transformation` function in `src/layout.rs` to `1.0`, before building Squeekboard.
Layout syntax
-------------

6
doc/tutorial.md
View File

@ -3,13 +3,13 @@ A guide to creating layouts
This guide is based on the original Kareema's [forum post](https://forums.puri.sm/t/translations-and-virtual-touch-keyboards-tracking-localization/7669/48).
It’s long overdue to write a comprehensive guide how to add a keyboard layout from start. But unfortunately, I don’t have much time left ATM. A lot of information can be found in [this](https://forums.puri.sm/t/using-non-latin-language-on-librem-5/7103/5) thread.
A lot of information can be found in [this](https://forums.puri.sm/t/using-non-latin-language-on-librem-5/7103/5) thread.
So at least I will try to start writing a short how-to here and edit this post as I find the time. Hope this helps a bit - comments and corrections [welcome](https://gitlab.gnome.org/World/Phosh/squeekboard/-/merge_requests/)
Comments and corrections [welcome](https://gitlab.gnome.org/World/Phosh/squeekboard/-/merge_requests/).
## Creating a new layout
Creating a layout is easy. You don't need to recompile things, just edit and test. It's easiest to start with an existing layout, with the [layouts](layouts.md) documentation in hand.
Creating a layout is easy. You do not need to recompile things, just edit and test. It is easiest to start with an existing layout, with the [layouts](layouts.md) documentation at hand.
### Get one of the existing keyboard layouts