~anjan/sxmo-docs-stable

4cf4b401d73c092b0544ed40810daf0a25d3d70c — Anjandev Momi 7 months ago 0c084bb + 4a9345b
Merge sxmo "pmos edge" docs branch into stable
2 files changed, 244 insertions(+), 200 deletions(-)

M SYSTEMGUIDE.md
M USERGUIDE.md
M SYSTEMGUIDE.md => SYSTEMGUIDE.md +11 -40
@@ 68,17 68,16 @@ Named runlevels in OpenRC are stored in directories under `/etc/runlevels`. When
    4) [networkmanager](https://git.alpinelinux.org/aports/tree/community/networkmanager/networkmanager.initd) 
    5) [chronyd](https://git.alpinelinux.org/aports/tree/main/chrony/chronyd.initd) 
    6) [modemmanager](https://gitlab.com/postmarketOS/pmaports/-/blob/master/temp/modemmanager/modemmanager.initd) 
    7) (eg25: broken link) 
    8) [eg25-manager](https://git.alpinelinux.org/aports/tree/community/eg25-manager/eg25-manager.initd) 
    9) [gpsd](https://git.alpinelinux.org/aports/tree/community/gpsd/gpsd.initd) 
    10) [gpsd_pinephone](https://gitlab.com/postmarketOS/pmaports/-/blob/master/device/main/device-pine64-pinephone/gpsd_pinephone.initd) 
    11) [rfkill](https://git.alpinelinux.org/aports/tree/main/util-linux/rfkill.initd)
    12) [sshd](https://git.alpinelinux.org/aports/tree/main/openssh/sshd.initd) 
    13) [swapfile](https://gitlab.com/postmarketOS/pmaports/-/blob/master/main/postmarketos-base/rootfs-etc-init.d-swapfile)  - note: swapfile size is 0, no swap is activated
    14) [sxmo-pinephone](https://git.sr.ht/~mil/sxmo-utils/tree/master/item/configs/openrc/sxmo-pinephone) 
    15) [udev-postmount](https://git.alpinelinux.org/aports/tree/main/eudev/udev-postmount.initd) 
    16) [tinydm](https://gitlab.com/postmarketOS/tinydm) - starts Display Manager
    17) [local](https://github.com/OpenRC/openrc/blob/master/init.d/local.in)  - this runs user-provided init scripts placed in the `/etc/local.d/` directory
    7) [eg25-manager](https://git.alpinelinux.org/aports/tree/community/eg25-manager/eg25-manager.initd) 
    8) [gpsd](https://git.alpinelinux.org/aports/tree/community/gpsd/gpsd.initd) 
    9) [gpsd_pinephone](https://gitlab.com/postmarketOS/pmaports/-/blob/master/device/main/device-pine64-pinephone/gpsd_pinephone.initd) 
    10) [rfkill](https://git.alpinelinux.org/aports/tree/main/util-linux/rfkill.initd)
    11) [sshd](https://git.alpinelinux.org/aports/tree/main/openssh/sshd.initd) 
    12) [swapfile](https://gitlab.com/postmarketOS/pmaports/-/blob/master/main/postmarketos-base/rootfs-etc-init.d-swapfile)  - note: swapfile size is 0, no swap is activated
    13) [sxmo-pinephone](https://git.sr.ht/~mil/sxmo-utils/tree/master/item/configs/openrc/sxmo-pinephone) 
    14) [udev-postmount](https://git.alpinelinux.org/aports/tree/main/eudev/udev-postmount.initd) 
    15) [tinydm](https://gitlab.com/postmarketOS/tinydm) - starts Display Manager
    16) [local](https://github.com/OpenRC/openrc/blob/master/init.d/local.in)  - this runs user-provided init scripts placed in the `/etc/local.d/` directory

## Display Manager - tinydm



@@ 210,35 209,7 @@ Some periodic components (the time by example) are triggered by the hook as a da
Some parts of the sxmo code are wrapped in hooks. If the user got the hook in their `~/.config/sxmo/hooks/` then this hook is used instead.
You can copy the default hooks from `/usr/share/sxmo/default_hooks` and modify, extend or remove some behaviors.

Here are the default hooks:

- `start`: Is run just after sway/dwm started. It start daemons
- `apps`: Output the Apps submenu content
- `scripts`: Ouptput the Scripts submenu content
- `notification`: Triggered on notification; make the phone to vibrate
- `sms`: Called when a sms come; trigger a sound and vibration
- `sendsms`: Called when you send a sms; trigger a sound
- `ring`: Called when a call is incoming; start the ring sound and vibrate
- `missed_call`: Called when you missed the call; make the ring to stop
- `mute_ring`: Called when you muted the call; stop the ring
- `pickup`: Called when you pickup the call; also stop the ring
- `discard`: Called when you discart the call; also stop the ring
- `contextmenu`: Output the main menu content
- `mnc`: Used by sxmo_screenlock.sh; Output when to wake up
- `vvm`
- `statusbar`: Is called with a subpart as argument. Update the status bar component
- `unlocksim`: Called when the sim need a simcode; Open a menu to type your sim code
- `desktop_widget`: Either start and manage conky or wayout
- `unlock`: Is triggered when the phone move to unlock mode; Start a 120s idle to move to lock
- `lock`: Is triggered when the phone move to lock mode; Start a 8s idle to move to off
- `screenoff`: Is triggered when the phone move to off mode; Start a 8s idle to move to crust
- `presuspend`: Trigger just before hibernation
- `postwake`: Trigger just after leaving hibernation
- `inputhandler`: Triggered before default sxmo input handler. Can be used to add gesture or context menu actions.
- `statusbar_periodics`: By default trigger some status bar component rebuild periodically. Extandable if you add your own components.
- `lisgdstart`: The command that start the lisgd daemon. Usefull if you want to add some gestures.
- `can_suspend`: Script that check if the phone can go in suspension
- `is_idle`: Script that check if the phone is idle and can go in a deepest state
A list of the default hooks can be found in the User Guide.

# Notifications


M USERGUIDE.md => USERGUIDE.md +233 -160
@@ 157,12 157,12 @@ that it can be the starting point to access much of the functionality
in Sxmo. This menu lets you:

- Launch [Scripts and Applications](#strongincluded-scripts-and-applicationsstrong)
- Adjust volume
- Make/Receive [Calls and Texts](#strongcalls-and-textingstrong)
- Launch the Camera
- Connect to Wifi and Cellular data (2G/3G/4G)
- Connect to Bluetooth (if bluez is installed)
- Adjust audio output device
- Adjust modem settings

**3. Global config menu (Config)**



@@ 170,7 170,6 @@ The global config menu is accessible by launching the global system menu
aforementioned and selecting *Config*. This menu let you:

- Adjust system brightness
- Toggle modem monitoring, view modem information and the modem log
- Rotate the screen rotation
- Upgrade packages
- Edit your configuration (your custom profile)


@@ 230,7 229,7 @@ When you are in deep sleep mode, you
can exit this mode and restore the above bindings by clicking the powerkey once.

To determine if the phone can lock deeper (from lock to off) and if it can
suspend (from off to deep sleep (crust)) sxmo relies on the hooks ``is_idle`` and ``can_suspend``
suspend (from off to deep sleep (crust)) sxmo relies on the hook ``check_state_mutexes``
respectively. You can override or replace those with your own custom rules.

### **Cron**


@@ 246,18 245,16 @@ dedicated script called ``sxmo_rtcwake.sh`` which:
- puts the phone back to crust when done

```
*/15 * * * * sxmo_rtcwake.sh sleep 10 2>> ~/.cache/sxmo/logs/dwm.log
*/15 * * * * sxmo_rtcwake.sh sleep 10 2>> ~/.local/state/tinydm.log
```

This example will wake the phone up for 10 seconds every 15 minutes. You may want to redirect the
standard error output to the main log as shown in the example above. You can pass the ``--strict``
parameter to ``sxmo_rtcwake.sh`` to only run when the phone is indeed in crust mode, otherwise it
will run regardless of the lock state.
standard error output to the main log as shown in the example above.

If you omit ``sxmo_rtcwake.sh`` for a job, the system will *not* wake up from crust.  Note that in such cases, you might want to use ``sxmo_wm.sh execwait`` instead, e.g.:

```
*/15 * * * * sxmo_wm.sh execwait sleep 20 2>> ~/.cache/sxmo/logs/dwm.log
*/15 * * * * sxmo_wm.sh execwait sleep 20 2>> ~/.local/state/tinydm.log
```

This will make sure that the SXMO environmental variables are sent to your script.


@@ 303,7 300,7 @@ Alternatively, you can do so from the command-line as follows:
mmcli -i 0 --pin 1234
```

You could put this in your unlock sim hook (``~/.config/sxmo/hooks/unlocksim``), but there is of course a
You could put this in your unlock sim hook (``~/.config/sxmo/hooks/sxmo_hook_modem.sh``), but there is of course a
significant security risk involved if your device gets compromised!

**Calling**


@@ 410,7 407,7 @@ have a contact stored associated with the incoming number, the contact
name will appear instead of the number. Also contact names will appear
in the Texts and Dialer menus if they are present in the contacts TSV
file. If no `contacts.tsv` is present, or the number is missing from
this file; the contact in menus will show up as `Unknown Number`.
this file; the contact in menus will show up as `???`.
An `contacts.tsv` example might look like:

```


@@ 538,7 535,9 @@ refer to [the changelog](./CHANGELOG.md).

## **User Customizable Functionality**

### **Files and Folders**
### **General Settings**

All files listed below should be in $XDG_CONFIG_DIR (usually: ~/.config/sxmo/).

<table>
  <tbody>


@@ 547,27 546,22 @@ refer to [the changelog](./CHANGELOG.md).
      <td><strong>Description</strong></td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/profile</td>
      <td>profile</td>
      <td>This file is loaded before starting dwm or sway. You should use it
      to configure environment variable. Note that /etc/profile.d/* and your
      own $HOME/.profile will be loaded before by tinydm.</td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/xinit</td>
      <td>xinit</td>
      <td>Automatically executed script executed upon starting X. (not used for Sway/Wayland).</td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/sway</td>
      <td>sway</td>
      <td>Sway configuration file (not used for dwm/Xorg), sets key bindings, wallpaper etc...
      You can also trigger commands in it with "exec".</td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/start [^1]</td>
      <td>This is a good place to set the wallpaper for instance, or to start
      some daemons</td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/contacts.tsv</td>
      <td>contacts.tsv</td>
      <td>
        <p>TSV file wherein each row is: contactnumber TAB contactname</p>
        <p>If unset all contacts will show up as 'Unknown Number'</p>


@@ 575,7 569,7 @@ refer to [the changelog](./CHANGELOG.md).
      </td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/block.tsv</td>
      <td>block.tsv</td>
      <td>
        <p>TSV file wherein each row is: blockedcontactnumber TAB blockedcontactname</p>
        <p>All phone numbers must be full phone numbers startings with + and the country code</p>


@@ 585,150 579,187 @@ refer to [the changelog](./CHANGELOG.md).
      </td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/sfeedrc</td>
      <td>sfeedrc</td>
      <td>Sfeedrc file (see <a href="https://codemadness.org/git/sfeed/file/README.html">sfeed documentation</a> used by RSS script)</td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/userscripts</td>
      <td>userscripts</td>
      <td>Directory or file to place user scripts which will automatically appear in the menu system</td>
    </tr>
  </tbody>
</table>

### **Hooks**

If a user-defined hook file does not exist on activity, sxmo will run the
corresponding project defined default hook from `/usr/share/sxmo/default_hooks/`.
For example, if you pickup a call and `$XDG_CONFIG_HOME/sxmo/hooks/sxmo_hook_pickup.sh` does
not exist, `/usr/share/sxmo/default_hooks/sxmo_hook_pickup.sh` will be run.

Note also that some hooks will be in a subdirectory with a devicename.  For
instance, in `/usr/share/sxmo/default_hooks/` there are `one_button_ereader`
and `three_button_touchscreen` and various names linked to them.  (We determine
the name of your device by looking at
`/sys/firmware/devicetree/base/compatible`.) This allows you to have unique
hooks depending on the kind of device that you are running.

<table>
  <tbody>
    <tr>
      <td>hooks/sxmo_hook_start.sh</td>
      <td>This is a good place to set the wallpaper for instance, or to start
      some daemons</td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/ring [^1]</td>
      <td>hooks/sxmo_hook_ring.sh</td>
      <td>
      <p>Executable script to run when the phone is receiving a call / rings</p>
      <p>This script is called with "$1" set to the contact name or incoming number if not in contacts.</p>
      </td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/pickup [^1]</td>
      <td>hooks/sxmo_hook_pickup.sh</td>
      <td>
      <p>Executable script to run when the phone is accepting an incoming call</p>
      </td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/missed_call [^1]</td>
      <td>hooks/sxmo_hook_missed_call.sh</td>
      <td>
      <p>Executable script to run when the phone missed an incoming call</p>
      <p>This script is called with "$1" set to the contact name or incoming number if not in contacts.</p>
      </td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sms [^1]</td>
      <td>hooks/sxmo_hook_sms.sh</td>
      <td>
      <p>Executable script to run when the phone is receiving a text</p>
      <p>Executable script to run when the phone is receiving a text, mms, or vvm (visual voice mail)</p>
      <p>This script is called with "$1" set to the contact name or incoming number if not in contacts and "$2" the actual text.</p>
      <p>If it is a group text, "$1" is set to the sender's contact name (or number if not in contacts) followed by a space
      followed by the group's contact name (or number if not in contacts) in between pointed brackets, e.g., Bob <MyFamily></p>
      <p>As well, if this is a Visual Voice Mail or an MMS, "$3" will be set to the payload ID.</p>
      <p>Finally, if this is a Group Text, "$4" will be set to the group contact name or number if not in contacts.</p>
      </td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/sendsms [^1]</td>
      <td>hooks/sxmo_hook_sendsms.sh</td>
      <td>
      <p>Executable script to run when the phone has just sent a text</p>
      <p>This script is called with "$1" set to the number and "$2" the actual text.</p>
      <p>This script is called with "$1" set to the number (or contact name) and "$2" the actual text.</p>
      </td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/is_idle [^1]</td>
      <td>hooks/sxmo_check_state_mutexes.sh</td>
      <td>
      <p>Check script run before going deeper in screen lock levels</p>
      <p>This script must return a non zero exit code if the phone cannot lock deeper</p>
      <p>This script contains various rules for programs that should block suspend and/or locking.</p>
      </td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/can_suspend [^1]</td>
      <td>
      <p>Check script run before suspending the system</p>
      <p>This script must return a non zero exit code if the phone cannot suspend at the time the script is invoked</p>
      </td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/statusbar [^1]</td>
      <td>
        <p>This script contain methods to update some status bar components. See SYSTEMGUIDE</p>
      <td>hooks/sxmo_hook_statusbar.sh</td>
	      <td>
		<p>This script contain methods to update some status bar components. See SYSTEMGUIDE</p>
	      </td>
	    </tr>
	    <tr>
	      <td>hooks/sxmo_hook_apps.sh</td>
	      <td>Executable script to run when display of the app menu is requested, outputs to stdout and allows you to override the default app
	      menu (see sxmo_appmenu.sh)</td>
	    </tr>
	    <tr>
	      <td>hooks/sxmo_hook_scripts.sh</td>
	      <td>Executable script to run when display of the scripts menu is requested, outputs to stdout and allows you to override the default app
	      menu (see sxmo_appmenu.sh)</td>
	    </tr>
	    <tr>
	      <td>hooks/sxmo_hook_presuspend.sh</td>
	      <td>Executable script that is executed prior to suspending the device. If the exit code of this script is
	      non-zero, suspend will be cancelled</td>
	    </tr>
	    <tr>
	      <td>hooks/sxmo_hook_postwake.sh</td>
	      <td>Executable script that is executed after waking from suspension. </td>
	    </tr>
	    <tr>
	      <td>hooks/DEVICENAME/sxmo_hook_lock.sh</td>
	      <td>Executable script that is executed prior to locking the device</td>
	    </tr>
	    <tr>
	      <td>hooks/DEVICENAME/sxmo_hook_unlock.sh</td>
	      <td>Executable script that is executed immediately after unlocking the device</td>
	    </tr>
	    <tr>
	      <td>hooks/sxmo_hook_lisgdstart.sh</td>
	      <td>Script that is executed to start the gesture deamon, overrides the defaults (see ``sxmo_lisgdstart.sh``). This
	      allows defining custom gestures.</td>
	    </tr>
	    <tr>
	      <td>hooks/sxmo_hook_stop.sh</td>
	      <td>Executable script that is executed immediately after closing the window manager (dwm/sway)</td>
	    </tr>
	    <tr>
	      <td>hooks/DEVICENAME/sxmo_hook_inputhandler.sh</td>
	      <td>Script that is executed when a gesture is to be interpreted. It is passed the WM_CLASS of the active window as
	      first parameter and the identifier/name of the gesture (or command to run) in the second argument, as configured with lisgd. See
	      ``sxmo_inputhandler.sh`` for details. This script allows you to define your own context-sensitive (i.e. application
	      specific) gestures.
	      </td>
	    </tr>
	    <tr>
	      <td>hooks/sxmo_hook_discard.sh</td>
	      <td>This script is executed (asynchronously) when you discard an incoming
	      call
	      </td>
	    </tr>
	    <tr>
	      <td>hooks/sxmo_hook_mute_ring.sh</td>
	      <td>This script is executed (asynchronously) when you mute an incoming call
	      </td>
	    </tr>
	    <tr>
	      <td>hooks/sxmo_hook_notification.sh</td>
	      <td>This script will run whenever any kind of notification is received. It can be used for example to blink the
	      led if you want to override the default behaviour</td>
	    </tr>
	    <tr>
	      <td>hooks/sxmo_hook_modem.sh</td>
	      <td>This hook will run when the modem changes state.  This is where you can use custom code if the SIM is locked.
		    You can consider putting
		    something like ``mmcli -i 0 --pin 1234`` in it to unlock automatically, if you don't mind the negative security implications
		    that carries in case your device gets compromised.</td>
	    </tr>
	    <tr>
	      <td>hooks/sxmo_hook_desktopwidget.sh</td>
	      <td>This script is run after the window manager starts to provide a desktop widget (like a clock)</td>
	    </tr>
	    <tr>
	      <td>hooks/sxmo_hook_suspend.sh</td>
	      <td>This script is run when system suspends.  It contains the actual suspend call.
	      </td>
	    </tr>
	    <tr>
	      <td>hooks/sxmo_hook_rotate.sh</td>
	      <td>This script is called when we rotate.  $1 is the new orientation (normal, left, right).
	      </td>
	    </tr>
	    <tr>
	      <td>hooks/sxmo_hook_icons.sh</td>
	      <td>This script is called every time we load a script.  You can override icons here.
	      </td>
	    </tr>
	    <tr>
	      <td>hooks/sxmo_hook_contextmenu.sh</td>
	      <td>This script is called when a menu is loaded.  You may override or add new menu options here.
	      </td>
	    </tr>
	    <tr>
      <td>hooks/DEVICENAME/sxmo_hook_inputmenu.sh</td>
      <td>This script is called when a (hardware) button is pressed or a touchscreen gesture occurs.  
	You can override the default button mappings here.
      </td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/apps</td>
      <td>Executable script to run when display of the app menu is requested, outputs to stdout and allows you to override the default app
      menu (see sxmo_appmenu.sh)</td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/scripts</td>
      <td>Executable script to run when display of the scripts menu is requested, outputs to stdout and allows you to override the default app
      menu (see sxmo_appmenu.sh)</td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/presuspend [^1]</td>
      <td>Executable script that is executed prior to suspending the device. If the exit code of this script is
      non-zero, suspend will be cancelled</td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/postwake [^1]</td>
      <td>Executable script that is executed after waking from suspension. </td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/lock [^1]</td>
      <td>Executable script that is executed prior to locking the device</td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/unlock [^1]</td>
      <td>Executable script that is executed immediately after unlocking the device</td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/lisgdstart [^1]</td>
      <td>Script that is executed to start the gesture deamon, overrides the defaults (see ``sxmo_lisgdstart.sh``). This
      allows defining custom gestures.</td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/stop [^1]</td>
      <td>Executable script that is executed immediately after closing the window manager (dwm/sway)</td>
    </tr>
    <tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/inputhandler [^1]</td>
      <td>Script that is executed when a gesture is to be interpreted. It is passed the WM_CLASS of the active window as
      first parameter and the identifier/name of the gesture (or command to run) in the second argument, as configured with lisgd. See
      ``sxmo_inputhandler.sh`` for details. This script allows you to define your own context-sensitive (i.e. application
      specific) gestures.
      </td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/discard [^1]</td>
      <td>This script is executed (asynchronously) when you discard an incoming
      call
      </td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/mute_ring [^1]</td>
      <td>This script is executed (asynchronously) when you mute an incoming call
      </td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/notification [^1]</td>
      <td>This script will run whenever any kind of notification is received. It can be used for example to blink the
      led if you want to override the default behaviour</td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/unlocksim [^1]</td>
      <td>This hook will run when your SIM needs to be unlocked with a PIN code. You can consider putting
            something like ``mmcli -i 0 --pin 1234`` in it to unlock automatically, if you don't mind the negative security implications
            that carries in case your device gets compromised.</td>
    </tr>
    <tr>
      <td>$XDG_CONFIG_HOME/sxmo/hooks/desktopwidget [^1]</td>
      <td>This script is run after the window manager starts to provide a desktop widget (like a clock)</td>
    </tr>
  </tbody>
</table>

Note: `$XDG_CONFIG_HOME` by default is equal to `~/.config`

[^1]: If a user-defined hook file does not exist on activity, sxmo will run the
corresponding project defined default hook from `/usr/share/sxmo/default_hooks/`.
For example, if you pickup a call and `$XDG_CONFIG_HOME/sxmo/hooks/pickup` does
not exist, `/usr/share/sxmo/default_hooks/pickup` will be run. More details
about hooks in SYSTEMGUIDE.


### **Logging**


@@ 753,7 784,7 @@ Note: `$XDG_CACHE_HOME` by default is equal to `~/.cache`

### **Environment Variables**

The following environment variables can be set:
The following environment variables can be set in `~/.config/sxmo/profile`:

<table>
  <tbody>


@@ 774,6 805,10 @@ The following environment variables can be set:
      <td>Keyboard to launch on single-clicking power button and used in scripts. Defaults to `svkbd-mobile-intl` or `svkbd-sxmo`</td>
    </tr>
    <tr>
      <td>$KEYBOARD_ARGS</td>
      <td>Arguments to pass to $KEYBOARD, e.g., `-o | clickclack -f /usr/share/sxmo/keytap.wav`</td>
    </tr>
    <tr>
      <td>$EDITOR</td>
      <td>Editor to use to handle files (partial support; full support plans for composing texts etc). Defaults to `vis`.</td>
    </tr>


@@ 793,10 828,6 @@ The following environment variables can be set:
      </td>
    </tr>
    <tr>
      <td>$SXMO_NO_ICONS</td>
      <td>Boolean, set to 1 if you don't want any icons shown in the menus</td>
    </tr>
    <tr>
        <td>$SVKBD_ENABLEOVERLAYS</td>
        <td>Boolean, set to 0 to disable the overlay functionality on the virtual keyboard (svkbd) (enabled by default), the overlay
        functionality is responsible for showing input variations such as diacritics when holding a key with a long press.</td>


@@ 815,11 846,11 @@ The following environment variables can be set:
        <td>Boolean value specifying whether dmenu interfaces should wrap around to the top/bottom of the list while scrolling. Set to `true` to enable (disabled by default).</td>
    </tr>
    <tr>
        <td>$LISGD_THRESHOLD</td>
        <td>$SXMO_LISGD_THRESHOLD</td>
        <td>Integer expressing the distance a gesture much minimally have to be recognized (unit corresponds to pixels usually)</td>
    </tr>
    <tr>
        <td>$LISGD_THRESHOLD_PRESSED</td>
        <td>$SXMO_LISGD_THRESHOLD_PRESSED</td>
        <td>Integer expressing the distance a gesture much minimally have to be recognized for gestures that act when pressed (such as volume/brightness control and scrolling) (unit corresponds to pixels usually)</td>
    </tr>
    <tr>


@@ 833,47 864,84 @@ The following environment variables can be set:
  </tbody>
</table>


The best place to set these default environment variables is in your ``~/.profile``
or in ``~/.config/sxmo/profile`` if they are sxmo specific.

### **Update migrations**
Other environmental variables that are more device specific can be found in README.md file in deviceprofiles/ in the source.

While developing Sxmo, we will regularly update certain configuration files such as the xinit/sway template, the
hooks or whatever. These files are typically a mixture of changes by us, and customizations by the user. This mixture
gives the user maximum flexibility to adapt Sxmo to his/her liking. This does imply that, when we update
such files, the challenge is to ensure that user modifications can be easily merged back in again, and that the system
is never in a broken state because of outdated configurations and version mismatches.

Whenever your configuration files are out-of-date when starting Sxmo, they will be moved aside (i.e. renamed with
``.needs-revision`` extension) and the default configuration will take its place. A red notification will pop up telling you
have configuration files that need to be migrated. This migration is done
by running a script named `sxmo_migrate.sh`. This script can simply be launched from the configuration menu.
It first shows the differences between your configuration and the new default, and allows you to edit and apply your
configuration accordingly.
### **Update migrations**

If you have any pending migrations, always make sure to complete the migration process before making any new changes to your
configuration. It is also recommended to keep your configuration under version control (e.g. git).
While developing Sxmo, we will regularly update certain configuration
files such as the xinit/sway template, the hooks or whatever. These
files are typically a mixture of changes by us and customizations by
the user. This mixture gives the user maximum flexibility to adapt Sxmo
to their liking. However, when we update such files, the challenge is
to ensure that user modifications can be easily merged back in again.
Moreover, we must ensure the system is never in a broken state because
of outdated configurations and version mismatches.

Whenever your configuration files are out-of-date when starting Sxmo,
they will be moved aside (i.e. renamed with ``.needs-revision`` extension)
and the default configuration will take its place. A red notification
will pop up telling you have configuration files that need to be
migrated. This migration is done by running a script named
`sxmo_migrate.sh`. This script can simply be launched from the
configuration menu or via ssh (recommended).
It first shows the differences between your configuration and the new
default, and allows you to edit and apply your configuration accordingly.
`sxmo_migrate.sh` use `$DIFFTOOL` to help you merge your changes. By default
`$DIFFTOOL` is set to `vimdiff`.

If you have any pending migrations, always make sure to complete the
migration process before making any new changes to your configuration.
It is also recommended to keep your configuration under version control
(e.g. git).

*Techical details*:

Sxmo (since 1.8.1) uses explicitly versioned configuration files, meaning that they each carry a simple version number unique to
the file, this version number is expressed in a comment in the file itself, such as:
Sxmo (since 1.8.1) uses explicitly versioned configuration files, meaning
that they each carry a simple version hash unique to the file.
This version hash is expressed in a comment in the file itself, such as:

```
# configversion: 1
# configversion: d8aaf01c9489793bda3686ef23b2b192
```

You should **only** update this version number when ``sxmo_migrate.sh`` prompts you to do so by showing a diff with a newer
configversion number.
You should **only** update this version hash when ``sxmo_migrate.sh``
prompts you to do so by showing a diff of a newer configversion hash.

If you want to see what files are disabled and need migration, run
``sxmo_migrate.sh state``, or run ``sxmo_migrate.sh sync state`` if
you just performed an upgrade and haven't restarted yet. If you want to
revert **all** your configuration files to the default, then you can
run ``sxmo_migrate.sh reset``. This is usually a last resort if you
end up with a broken system and can be considered a kind of factory
reset, all your configuration files will moved out of the way and
flagged for migration then.

The process that checks the versions of your configuration files is
``sxmo_migrate.sh sync``, it runs automatically when Sxmo starts.

### Resolving system configs on system upgrade and make

Apk will install new configs as
`.apk-new` on upgrades if you have modified the original config in `/etc`.
Moreover, when hacking on Sxmo, you will often run `make install`and this may "modify" 
a config in /etc from apk's perspective.
You can merge apk's config changes by running `doas update-conf`. You can also run `apk audit` 
to list all the files that have changed from what apk originally installed.


### Resolving system configs on system upgrade and make

If you want to see what files are disabled and need migration, run ``sxmo_migrate.sh state``, or run ``sxmo_migrate.sh
sync state`` if you just performed an upgrade and haven't restarted yet. If you want to revert **all** your
configuration files to the default, then you can run ``sxmo_migrate.sh reset``. This is usually a last resort if you end
up with a broken system and can be considered a kind of factory reset, all your configuration files will moved out of
the way and flagged for migration then.
Apk will install new configs as
`.apk-new` on upgrades if you have modified the original config in `/etc`.
Moreover, when hacking on Sxmo, you will often run `make install`and this may "modify" 
a config in /etc from apk's perspective.
You can merge apk's config changes by running `doas update-conf`. You can also run `apk audit` 
to list all the files that have changed from what apk originally installed.

The process that checks the versions of your configuration files is ``sxmo_migrate.sh sync``, it runs automatically when
Sxmo starts.

### Resolving system configs on system upgrade and make



@@ 906,14 974,19 @@ Create a file ``~/.Xresources`` and you have the following notable settings to t

User scripts are custom scripts the user can run via the [global
system menu](#strongincluded-menusstrong). To add your own custom
userscript:
userscript, you have two options: edit the `userscripts` file or
place a shell script in the `userscripts` directory.

- either create the `$XDG_CONFIG_HOME/sxmo/userscripts` directory and place your
`.sh` scripts in the `userscripts` directory. Note, Userscripts should be set to
be executable.
- or touch the `$XDG_CONFIG_HOME/sxmo/userscripts` file and write your entries
- Option 1. Edit `$XDG_CONFIG_HOME/sxmo/userscripts` and write your entries
in it, following the appmenu format `<name> ^ <should-return-to-menu> ^ <script-path-or-command>`
one entry per line. Example: ` Weather ^ 0 ^ sxmo_terminal.sh -f "monospace:size=5" sh -c "curl http://wttr.in/ | less -SR"`
- Option 2. Create the `$XDG_CONFIG_HOME/sxmo/userscripts` directory and place your
`.sh` scripts in the `userscripts` directory. Note, Userscripts should be set to
be executable. You can set a title for the script by adding a comment line of the following ofrmat near the top of the file:

```sh
# title="$icon_glb My World"
```

For examples of scripts Sxmo users have made for their mobile devices, see: