doc/*: Fix typos and add a few small improvements
Part-of: <https://gitlab.gnome.org/World/Phosh/squeekboard/-/merge_requests/642>
This commit is contained in:
MoonlightWave-12
@ -27,7 +27,7 @@ To give an idea of what it means in practice, those are some examples of what ha
|
||||
- storing resources and config as editable, standard files,
|
||||
- having complete, up to date documentation of interfaces,
|
||||
- having an easy process of sending contributions,
|
||||
- adapting to to user's settings and constrains without overriding them,
|
||||
- adapting to the user's settings and constraints without overriding them,
|
||||
- avoiding compiling whenever possible,
|
||||
- making it easy to build,
|
||||
- having code that is [simple and obvious](https://www.python.org/dev/peps/pep-0020/),
|
||||
@ -52,8 +52,8 @@ Recent Fedora releases are likely to be tested as well.
|
||||
On a Debian based system run
|
||||
|
||||
```sh
|
||||
sudo apt-get -y install build-essential
|
||||
sudo apt-get -y build-dep .
|
||||
$ sudo apt-get -y install build-essential
|
||||
$ sudo apt-get -y build-dep .
|
||||
```
|
||||
|
||||
For an explicit list of dependencies check the `Build-Depends` entry in the [`debian/control`](debian/control) file.
|
||||
@ -74,22 +74,22 @@ Most common testing is done in CI. Occasionally, and for each release, do perfor
|
||||
- it changes layouts
|
||||
- it changes views
|
||||
|
||||
Testing with an application:
|
||||
#### Testing with an application
|
||||
|
||||
```
|
||||
python3 tools/entry.py
|
||||
$ python3 tools/entry.py
|
||||
```
|
||||
|
||||
Testing visibility:
|
||||
#### Testing visibility
|
||||
|
||||
```
|
||||
$ busctl call --user sm.puri.OSK0 /sm/puri/OSK0 sm.puri.OSK0 SetVisible b true
|
||||
$ busctl call --user sm.puri.OSK0 /sm/puri/OSK0 sm.puri.OSK0 SetVisible b false
|
||||
```
|
||||
|
||||
Testing layouts:
|
||||
#### Testing layouts
|
||||
|
||||
Layouts can be selected using the GNOME Settings application.
|
||||
Available Layouts can be selected by using the GNOME Settings application.
|
||||
|
||||
```
|
||||
# define all available layouts. First one is currently selected.
|
||||
@ -101,7 +101,7 @@ $ gsettings set org.gnome.desktop.input-sources sources "[('xkb', 'us'), ('xkb',
|
||||
Squeekboard prints some information on standard output by default. To get deep debugging information, it can also print all changes in (some of) its internal state. Those logs are most useful when reporting hard to catch issues, and can be enabled using the following command:
|
||||
|
||||
```
|
||||
busctl set-property --user sm.puri.SqueekDebug /sm/puri/SqueekDebug sm.puri.SqueekDebug Enabled b true
|
||||
$ busctl set-property --user sm.puri.SqueekDebug /sm/puri/SqueekDebug sm.puri.SqueekDebug Enabled b true
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
@ -121,8 +121,8 @@ Coding
|
||||
Reference documentation can be generated using:
|
||||
|
||||
```
|
||||
cd squeekboard_build/
|
||||
../squeekboard_source/cargo.sh doc --no-deps --document-private-items
|
||||
$ cd squeekboard_build/
|
||||
$ .../squeekboard_source/cargo.sh doc --no-deps --document-private-items
|
||||
```
|
||||
|
||||
as well as found [online](https://world.pages.gitlab.gnome.org/Phosh/squeekboard/doc/rs/).
|
||||
@ -150,7 +150,7 @@ Note that some portions, like the .gitlab-ci.yml file have accummulated enough s
|
||||
To fix your contributions before submitting a change, use:
|
||||
|
||||
```
|
||||
./tools/style-check_source --apply
|
||||
$ ./tools/style-check_source --apply
|
||||
```
|
||||
|
||||
* * *
|
||||
@ -209,8 +209,8 @@ Squeekboard uses Rust & Cargo for some of its dependencies.
|
||||
Use the `cargo.sh` script for maintaining the Cargo part of the build. The script takes the usual Cargo commands, after the first 2 positional arguments: source directory, and output artifact. So, `cargo test` becomes:
|
||||
|
||||
```
|
||||
cd build_dir
|
||||
sh /source_path/cargo.sh test
|
||||
$ cd build_dir
|
||||
$ sh /source_path/cargo.sh test
|
||||
```
|
||||
|
||||
### Cargo dependencies
|
||||
@ -224,15 +224,15 @@ 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.
|
||||
|
||||
### 1. Update `Cargo.toml`.
|
||||
### 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.
|
||||
|
||||
```
|
||||
cd squeekboard-build
|
||||
.../squeekboard-source/cargo.sh update
|
||||
ninja test
|
||||
cp ./Cargo.lock .../squeekboard-source
|
||||
$ cd squeekboard-build
|
||||
$ .../squeekboard-source/cargo.sh update
|
||||
$ ninja test
|
||||
$ cp ./Cargo.lock .../squeekboard-source
|
||||
```
|
||||
|
||||
Then commit the updated `Cargo.lock`.
|
||||
@ -252,8 +252,8 @@ It's in the `project(version: xxx)` statement.
|
||||
Packaging is in the `debian/` directory, and creates builds that can be quickly tested.
|
||||
|
||||
```
|
||||
cd squeekboard-source
|
||||
EMAIL=my_address@example.com gbp dch --multimaint-merge --ignore-branch --git-author --distribution=experimental --new-version=x.y.z
|
||||
$ cd squeekboard-source
|
||||
$ EMAIL=my_address@example.com gbp dch --multimaint-merge --ignore-branch --git-author --distribution=experimental --new-version=x.y.z
|
||||
```
|
||||
|
||||
Inspect `debian/changelog`, and make sure the first line contains the correct version number and suite. For example:
|
||||
@ -264,7 +264,7 @@ squeekboard (1.22.0) experimental; urgency=medium
|
||||
|
||||
Add the updated `debian/changelog` to the commit. The commit message should contain the release version and a description of changes.
|
||||
|
||||
(`gbp` can be installed with `sudo apt install git-buildpackage`)
|
||||
(`gbp` can be installed on Debian based systems with `sudo apt install git-buildpackage`)
|
||||
|
||||
### 5. Update the NEWS file
|
||||
|
||||
@ -284,7 +284,7 @@ Changes:
|
||||
Generate a commit message from the NEWS file:
|
||||
|
||||
```
|
||||
tools/make_message | git commit --file=- ...
|
||||
$ tools/make_message | git commit --file=- ...
|
||||
```
|
||||
|
||||
If the commit message looks wrong, fix the NEWS file, and do `git commit --amend`.
|
||||
@ -294,8 +294,8 @@ If the commit message looks wrong, fix the NEWS file, and do `git commit --amend
|
||||
The tag should be the version number with "v" in front of it. The tag message should be "squeekboard" and the tag name. Push it to the upstream repository:
|
||||
|
||||
```
|
||||
git tag -s -u my_address@example.com v1.22.0 -m "squeekboard v1.22.0"
|
||||
git push origin v1.22.0
|
||||
$ git tag -s -u my_address@example.com v1.22.0 -m "squeekboard v1.22.0"
|
||||
$ git push origin v1.22.0
|
||||
```
|
||||
|
||||
### 8. Rejoice
|
||||
|
||||
@ -19,7 +19,7 @@ Each hint directory contains multiple layout files. A single language will be co
|
||||
|
||||
After the language name optionally comes a "+" and an indication of the variant. For example, "it+fur".
|
||||
|
||||
Squeekboard will look for those based on the currently selected layout in Gnome Control Center.
|
||||
Squeekboard will look for those based on the currently selected layout in GNOME Settings.
|
||||
|
||||
Then, there's an optional part "_wide", which Squeekboard will try to use if the current display is rather wide. Example: "us+colemak_wide" or "us_wide".
|
||||
|
||||
@ -40,6 +40,7 @@ The "outlines" dictionary controls the widths and heights of buttons.
|
||||
outlines:
|
||||
default: { width: 32, height: 52 }
|
||||
```
|
||||
|
||||
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:
|
||||
@ -118,4 +119,4 @@ 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.
|
||||
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.
|
||||
|
||||
@ -23,7 +23,7 @@ Creating a layout is easy. You don't need to recompile things, just edit and tes
|
||||
* Find the correct name of the .yaml file associated with that input source. This can be found with the command
|
||||
|
||||
```
|
||||
gsettings get org.gnome.desktop.input-sources sources
|
||||
$ gsettings get org.gnome.desktop.input-sources sources
|
||||
```
|
||||
|
||||
The output should be something like this: `[('xkb', 'us'), ('xkb', 'de')]`
|
||||
@ -40,13 +40,13 @@ The yaml file will overwrite the default settings for that layout. If you want t
|
||||
You can also use the `test_layout` tool from the -devel package to check it for errors:
|
||||
|
||||
```
|
||||
# squeekboard_test_layout ./mylayout.yaml
|
||||
$ squeekboard_test_layout ./mylayout.yaml
|
||||
Test result: OK
|
||||
```
|
||||
|
||||
## Contributing your changes
|
||||
|
||||
If you want to share your layout with the world, the best way is to submit it to the Squeekboard project. The workflow is similar to any other Gitlab-based project.
|
||||
If you want to share your layout with the world, the best way is to submit it to the Squeekboard project. The workflow is similar to any other GitLab-based project.
|
||||
|
||||
Above all, your layout should be working, be tested, not break anything, and make sense.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user