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

Improve Documentation

Browse Source 
Part-of: <https://gitlab.gnome.org/World/Phosh/squeekboard/-/merge_requests/642>
This commit is contained in:
MoonlightWave-12
2024-04-11 15:49:44 +02:00
parent cff687d778
commit 5de4a6ad92
5 changed files with 48 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
doc/hacking.md
View File

@ -43,9 +43,9 @@ By submitting a change to this project, you agree to license it under the [GPL l
Development environment
-----------------------
*Squeekboard* is regularly built and tested on [the development environment](https://developer.puri.sm/Librem5/Development_Environment.html).
*Squeekboard* is regularly built and tested on [Debian Testing](https://www.debian.org/releases/testing/) and [Mobian Testing](https://mobian.org/).
Recent Fedora releases are likely to be tested as well.
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
@ -91,6 +91,8 @@ $ busctl call --user sm.puri.OSK0 /sm/puri/OSK0 sm.puri.OSK0 SetVisible b false
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.
$ gsettings set org.gnome.desktop.input-sources sources "[('xkb', 'us'), ('xkb', 'de')]"
@ -113,6 +115,12 @@ contain a comma separated list of:
- `force-show` : Show squeekboard on startup independent of any gsettings or compositor requests
- `gtk-inspector`: Spawn [gtk-inspector](https://wiki.gnome.org/Projects/GTK/Inspector)
`GTK_THEME=` can be used to choose a theme other than the default theme for Squeekboard:
- `Adwaita:dark` is used for Squeekboard on Phosh.
- Other values that are not the name of an available theme (for example: `HighContrast`) will use the theme that is used while "High Contrast" is enabled in Phosh.
Coding
------
@ -215,14 +223,17 @@ $ sh /source_path/cargo.sh test
### Cargo dependencies
All Cargo dependencies must be selected in the version available in PureOS, and added to the file `debian/control`. Please check with https://software.pureos.net/search_pkg?term=librust .
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.
Releases
----------
--------
Squeekboard should get a new release every time something interesting comes in. Preferably when there are no known bugs too. People will rely on theose releases, after all.
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.
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`.
@ -240,8 +251,7 @@ Then commit the updated `Cargo.lock`.
### 2. Choose the version number
Squeekboard follows [Phosh's versioning](https://gitlab.gnome.org/World/Phosh/phosh/-/wikis/Releases).
For example: The first Squeekboard-release for Phosh 0.38 should have the version-number 1.38.0. The last part of the version number (1.38.x) may be incremented independently of Phosh's version for bug-fix-releases.
Feature-releases should me made before the release of the new version of Phosh, so that the release-notes can contain the news about Squeekboard.
For example: The first Squeekboard-release for Phosh 0.38 should have the version-number 1.38.0. The last part of the version number (1.38.x) may be incremented independently of Phosh's version for bug-fix-releases.
### 3. Update the number in `meson.build`

9
doc/index.md
View File

@ -4,12 +4,17 @@ Welcome to squeekboard's documentation!
Introduction
------------
Squeekboard is the on-screen keyboard for the Librem 5 phone. For information about building, look at the [README](README.md).
*Squeekboard* is the on-screen keyboard for Phosh. It is primarily designed for smartphones, tablet-PCs, and other devices with touchscreens.
Building
--------
For information about building Squeekboard, read the [README](README.md).
Layouts
-------
Squeekboard allows user-provided keyboard layouts. They can be created without recompiling the keyboard code. The [tutorial](tutorial.md) explains the process in detail.
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.
Layouts are created using a [text-based format, based on YAML](layouts.md).

28
doc/layouts.md
View File

@ -6,14 +6,14 @@ Squeekboard is composed of multiple layouts, several for each language, multipli
Layouts live in the "keyboards" directory.
Hints
-------
-----
The currently supported hints are: default, "email", "emoji", "number', "pin", "terminal", and "url".
Each directory in "keyboards" is named after a hint, with the "keyboards" directory itself taking the role of default.
Languages/scripts
-----------------------
-----------------
Each hint directory contains multiple layout files. A single language will be composed of multiple files, with names starting with the same text. The language names are taken from iso639-3. An example is "gr".
@ -27,8 +27,15 @@ Finally, the file name ends with ".yaml", e.g. "jp+kana_wide.yaml".
Together with hint information, this gives a complete path to the layout like this: "keyboards/terminal/fr_wide.yaml" or "keyboards/cz+qwerty.yaml".
Using custom layouts
--------------------
Custom layouts will be loaded from `~/.local/share/squeekboard/keyboards/`.
In addition to loading customised layouts for languages (for example: from `~/.local/share/squeekboard/keyboards/de.yaml`, for a custom layout for the German language), Squeekboard will also load layouts for "A user-defined custom layout" from `custom.yaml`, which can be added as a keyboard-layout in the keyboard-settings of GNOME Settings.
The included (and replaceable) layouts are in: `data/keyboards/`.
Layout syntax
------------------
-------------
The layout file follows the YAML syntax, with specific meanings given to sections.
@ -44,9 +51,13 @@ outlines:
The width and height numbers are not in pixels, but rather they are proportionally scaled to fit the panel size.
There may be any number of outlines, but there are some special names:
- "default" applies to every button unless explicitly changed. It should be used for buttons that emit text
- "altline", "wide" have own color scheme, should be used for buttons which cause view changes
- "special" has own color scheme, to be used for confirmations like enter.
- `default` applies to every button unless explicitly changed. It should be used for buttons that emit text.
- `change-view` has its own color scheme and a border at the bottom, it should be used for buttons which switch to a different view.
- `altline`, `wide` and `special` have their own color scheme, to be used for buttons with functionality other than entering text (for example: `Return` and `Backspace`).
- `subtle-highlight` has a slightly different colour than the `default`-buttons, to make commonly used buttons easier to find in views that are otherwise full of generally rarely used buttons (for example `ä`, `ö`, `ü`, and `ß`, in the `eschars`-view of the German layout).
Read `style.css`, `style-Adwaita:dark.css` and `common.css`, which are in the `data`-folder, for a complete list of outline-names with special styling.
### Views
@ -73,7 +84,7 @@ Each row is a single string, and button names are separated by spaces. In left-t
#### Button names in rows
Unicode characters are supported in the row string, so it's easy to use the correct name for most of them. However, the layout code is still YAML, which excludes certain characters: the space " ", the backslash "\", the double quote `"`. Those must use a replacement name.
Unicode characters are supported in the row string, so it's easy to use the correct name for most of them. However, the layout code is still YAML, which excludes certain characters: the space " ", the backslash "\", the double quote `"`. Those must either use a replacement name, or be written as `\\`, `\"`, or `"\""`, where required.
Similarly, buttons that do not emit characters must have some names.
@ -117,6 +128,7 @@ The "action" property has multiple forms.
The two switching modes are better described in the [views](views.md) document.
Sources
----------
-------
The sources, where all this is documented and up to date are in "src/data/parsing.rs". The reference documentation for the `rs::data::parsing::Layout` structure is the main place to look at.

5
doc/tutorial.md
View File

@ -86,7 +86,4 @@ If you want your change to become part of official Squeekboard, or if you want t
* Follow these instructions to run squeekboard: [README.md#running](https://gitlab.gnome.org/World/Phosh/squeekboard/-/blob/main/README.md#running)
* Additionally take a look at the contribution document for [testing info](https://gitlab.gnome.org/World/Phosh/squeekboard/-/blob/main/doc/hacking.md#testing)
* You can either test it locally on your Linux system or use the [QEMU Librem 5 image](https://developer.puri.sm/Librem5/Development_Environment/Boards/emulators.html)
* To test squeekboard locally, you need phoc. Either compile that from the sources as well or use the CI repository ci.puri.sm for Debian based systems:
`deb [arch=amd64] http://ci.puri.sm/ scratch librem5`
Squeekboard can be installed from there as a Debian package, too (that’s what I often do). But beware - there be dragons! You could bork your system with these packages and you should probably disable this repository again after installing what you need - these packages are not meant for production systems (or so I heard :wink: )
* To test squeekboard locally, you need [phoc](https://gitlab.gnome.org/World/Phosh/phoc). Either install it from a package for your distribution, for example with `sudo apt install phoc` for Debian based distributions, or compile it from the sources.