This is a minor release in order to update the codebase to build against
zig 0.10.1. This release tag, 1.1.2, builds against zig 0.10.1.
This is a minor release in order to update the codebase to build against
zig 0.10.0. The mepo 1.1 tag was built against zig 0.9.1. This release
tag, 1.1.1, builds against zig 0.10.0.
In addition to the build update to update to zig 0.10.0, the following
small bugfixes have been included:
- make userpin updater less verbose (thanks to laalsaas)
- fix user_pin_updater on all locales (thanks to laalsaas)
- Use TTF_RenderUTF8_Blended instead of TTF_RenderText_Blended, which
fixes the rendering of non-ascii text entities. (#57)
(thanks to hummer12007 for reporting this issue)
This release was focused on several feature and quality improvements
including: the addition of new pin_transfer & pin delete commands,
improvements to the bind_button command, switching to use for zenity
for menuing in all environments, and several other minor bugfixes and
feature updates. Major changes in this release cycle are described below:
1. Addition of new pin_transfer & pin_delete commands
A new command, pin_transfer, has been added which allows the user to
transfer pins from one group to another. This command makes saving &
combining target search resultsets (such as from Nominatim, Overpass
etc.) in the default configuration much simpler as you can simply move
pins from the search results (e.g. pin group 0) to other pin groups 0-9.
The pin_transfer command supports both moving a single pin from one group
to another, in addition to moving all pins in the group to another target
group. See either the manpage documentation or the mepolang documentation
website for information on using this command.
Additionally, another new command, pin_delete, has been added which
allows the user to delete a target pin by handle and also supports
deleting the currently active pin.
The pin_transfer & pin_delete commands are used in conjunction in the
default configuration with updates to the bind_button command (described
below) to expose this functionality to end-users in the UI. These two
commands are also exposed as keybindings; the new keybindings are covered
in the last section of these release notes.
2. Top UI buttons & bind_button improvements
The bind_button command's functionality has been greatly improved in this
release in three ways: 1) bind_button's visible_only_when_pin_active
argument now automatically positions buttons along the top of the UI
(above the pin detail overlay) when a pin is active, 2) bind_button now
allows associating a group number with the button (and thus indicating
the pin group color on the button and also highlighting the button when
the associated pin group is active), and 3) supporting click vs hold
functionality to dispatch different mepolang code if the button is held
versus clicked.
These 3 changes open up numerous usecases for end-users; and in the
default configuration, end-users will note this functionality has been
utilized so that 0-9 buttons are now visible in the top bar alongside
the pin details overlay. Clicking 0-9 will transfer the currently active
pin to the target group and holding 0-9 will transfer all pins in the
current group to the target group. The colors for each group are shown
in the top bar and it is now easier to determine which group you're
currently activated on and move pins between groups. In addition, `Del`
and `~` buttons have been added to the new top button bar to allow for
deleting the currently active pin and toggling the verbosity of the pin
detail overlay respectively. The buttons for switching between pins &
purging the current pin group have been moved from the bottom button bar
to the top button bar as well. The userguide has been updated to detail
these end-users changes.
3. Menuing switched to use zenity for all environments; dmenu/bemenu dep removed
Zenity has been switched to be the sole menuing option for mepo's scripts
after determining this method is well supported in all environments in
testing based on the last release cycle. Zenity provides a separate
window for user input and list selection, rather then a dock window,
which provides good cross-environment compatibility for Phosh, Sxmo,
Plasma Mobile, desktop X, and desktop Wayland environments.
Using zenity, dependencies on dmenu & bemenu have been removed and
packaging & end-user installation is now simplified as users do not have
to determine the menuing system to use. To this end, the logic for dmenu
& bemenu menuing has been removed entirely, however it should be noted
for end-users who would prefer legacy style dmenu or bemenu menuing
the `MEPO_MENUING` env variable may be used with a custom script in
if desired.
The polishing and completeness around zenity's integration has also
been improved. In the 1.0 release, zenity had icon glyphs not shown
properly. The icon glyphs used for zenity used are now more common &
available with the default monospace font on Alpine Linux. Additionally,
in 1.0, the overpass script presented so many options that the zenity
menuing had to show multiple pages for item selection; to address this,
the number of results has been reduced and only a single page is shown
for the overpass POI search script. And finally on zenity integration
polishing, on X-based environments where zenity is set to be a floating
window, xwininfo is used to automatically determine and place the sizing
of the window.
In this release, packagers should note to remove dependencies on: bemenu,
xdotool, dmenu, and font-inconsolata-nerd. And packagers should add
dependencies for zenity, findutils, and xwininfo.
4. Misc bugfixes & feature improvements
A few other miscellaneous bugfixes and feature improvements have been
made in this release cycle I'd like to mention here:
Firstly, an outstanding bug relating to the geolocation / user pin updater
script has been made such that Geoclue and MLS are now preferred over
GPSd as the default geolocation positioning provider. In prior releases
if you used the user pin updater script (e.g. by pressing `Center`
in the UI) and had not properly configured GPSd, the entire UI would
freeze up. The reason for this is that in most scenarios GPSd needs to
be configured by end-users manually and without quick fix acquisition (as
is an ongoing issue with the Pinephone and eg25manager), it's better for
us to use Geoclue by default and allow Geoclue to dispatch the provider
used automatically. MLS is the second fallback now, and GPSd is last.
It should be noted, Geoclue will use GPSd in anycase if configured and
available on the user's system. For end-users who want to customize
the provider function used for geolocation lookups, they may use the
new `MEPO_GEOLOCATE_COORDSVIAMETHOD` env variable which is documented in
the userguide.
Secondly, some preferences have been changed in the default configuration
such as for pin group colors, pin group ordering, and a new preference,
overlay_pindetails_expanded, has been introduced to allow the user to
toggle the verbose of the pin detail overlay. If you notice strangeness
when upgrading to this release (with pin groups), it's recommended
to purge your savestate cache at ~/.cache/mepo/savestate which may
incorporate 1.0 defaults and override the 1.1 defaults. The 1.1 defaults
will be automatically installed if ~/.cache/mepo/savestate is missing.
Thirdly, the display for pins has changed slightly such that the active
pin now shows its label with a gray background and with the pin having
a red outline then being fully red. This change was made to make the
the active pin & pin group more clear to end-users. When transferring
the active pin between groups, as is now a simple operation in the UI
with changes mentioned above in (2), there is a clear visual indication
of this.
And finally, the default configuration has been updated to incorporate
a few new hotkeys based on new application functionality added in
this release cycle: shift + 0-9 will move a pin to the target group,
control + shift + 0-9 will move all pins in your current group to the
target group using pin_transfer, the d hotkey now deletes the current
pin, shift d deletes all pins in the current group, and shift -/+ now
adjusts the UI fontsize. These hotkeys may be referenced further by
examining the bind_key commands set in the default configuration which
may be referenced either in the manpage or the documentation website.
This release was focused on completing documentation and polishing
features to finalize the roadmap and address Milestone 6. In addition,
this release also added support for Plasma Mobile and alternative UI
environments by way of adding support for menuing to mepo's scripts via
zenity to address Milestone 8. A manpage documentation generator has been
added under a CLI flag and the markdown API documentation generator CLI
flag has been reworked to be more exhaustive. End-user documentation has
been moved to a separate repository mepo_website as part of the launch of
the new documentation website http://mepo.milesalan.com. Major features
changes in this release cycle are described below:
1. Mepo scripts customizable ENV variables
All ENV variables considered potentially privacy-concerning such as
URL endpoints connected to the default public instances of Nominatim,
Overpass, and GraphHopper have been updated to be user-customizable
rather then being hardcoded. These environment variables all start with
`MEPO_` and can be seen documented along with default values on the new
mepo documentation website's user guide or can be referenced from each
script directly.
In addition to URL endpoints and API keys now being customizable, a
number of feature-related ENV variables have been introduced such as
MEPO_USERPIN_ENABLED which allows for the enabling or disabling of the
default user pin location updating script. MEPO_USERPIN_ENABLED may be set
to 0 to disable the default user positioning pin dropping. Additionally,
a newly introduced environment variable, MEPO_MENUING, allows for
customization of the menuing program (bemenu, dmenu, or zenity) used
for menuing and user input in scripts. The user may set MEPO_MENUING
to either inputbemenu, inputdmenu, or inputzenity to use bemenu, dmenu,
or zenity respectively.
2. Plasma Mobile & Alternative environments support: Zenity & OSK detection
Zenity has been added as a menuing/user input method for mepo's
scripts. Primarily the motivation behind adding zenity support is that
compatibility on Plasma Mobile is best with a proper separate window
rather then a dock menu. In addition, zenity is now used as a fallback
method where bemenu or dmenu is not available. As mentioned in (1),
the new MEPO_MENUING environment variable has been introduced to support
user customization of their preferred menuing method. Zenity is generally
the most UI platform cross-compatible menuing option and is additionally
used as the default in the newly added mepo flatpak.
In addition to changes made to support zenity, which is used for Plasma
Mobile.. testing has also taken place and minor changes have been made
in the Zig codebase similar to changes for Phosh to automatically hide
the onscreen keyboard when not necessary on Plasma Mobile.
These two changes (menuing support via zenity; and tweaks for Plasma
Mobile's OSK), makes Plasma Mobile a first-class supported target
for mepo. The 3 major mobile environments which mepo now supports
match postmarketOS's 3 major mobile UI environments of: Sxmo, Phosh,
and Plasma Mobile. Other environments will likely benefit as well from
zenity support too.
3. Manpage & Markdown API documentation generation
A new commandline flag -docman had been added to allow for the generation
of a manpage which covers all mepolang commands, preferences, commandline
flags, and the default config. While the website is more exhaustive in
covering user guides, integrating images and demo videos; the manpage
can serve as a good entrypoint for beginner or advanced users who do
not wish to use the documentation website.
Packagers should use the manpage generator flag and save to a `.1` file
in the build process for the manpage to be distributed in documentation
packaging. For example: `mepo -docman > /usr/share/man/man1/mepo.1`. As
for end users, in distributions which documentation may not have been
properly installed, having the manpage doc be generated directly from
the binary now also allows direct viewing from mepo's CLI via man using
man's `-l` flag. For example to view the manpage directly from the mepo
CLI you can now simply run: `mepo -docman | man -l`.
In addition to the new -docman flag, the -docmd flag available in prior
versions of mepo which generates dynamic mepolang documentation has been
extended upon to include preference table generation, commandline flags
and the default config documentation to have parity with the generated
manpage. The markdown document generated from the -docmd commandline flag
is used in the build system for the new mepo documentation website and the
rendered result can be seen at http://mepo.milesalan.com/mepolang.html.
4. Documentation guides moved to mepo_website repository
All markdown-based documentation which previously resided
in the `doc/` folder has been moved to be hosted within the
new mepo_website repository. This repository is available at
http://sr.ht/~mil/mepo_website and is responsible for generating the
static site for http://mepo.milesalan.com
The new documentation mepo website at http://mepo.milesalan.com covers
an install guide, user guide, scripting guides, and more. Demo videos and
new screencasts have been created which are hosted at this site as well.
This new website is the official 'source-of-truth' for all things mepo
documentation rather then the previous `doc/` folder within the mepo
repository.
Add 128x128 and 512x512 icons to install to build
This release was focused on polishing UI feature completeness including:
(1) a rework of the preference system and the introduction of save/restore
state, (2) interactive debugging via STDIN, (3) the introduction of an
async shellpipe variant (along with bookmarking and user positioning
shell scripts), and (4) several smaller miscellaneous features.
1. Preference system overhaul & introduction of save/restore state
The preference system has been reworked in order to support save/restore
state and internal state within the application now has a degree of
consistency not present in prior versions. 0.4 and prior versions of
mepo featured several separate commands for setting pingroup properties,
zoom-level, latitude/longitude and other preferences. As of this release,
all preferences can now be set with two commands: `prefset_n` and
`prefset_t`.
This consistency has paved the way for a new `filedump` command which
allows the user to save the current state of the application (zoom level,
latitude/longitude, pins, etc.) to an arbitrary file. In the new default
config, via a new `bind_quit` hook, the application's state is saved
on quitting and restored on boot. The net effect end-users will notice
is that closing the application and opening it back up will restore the
application positioning, pins, etc.
While save/restore state via `bind_quit` is the new default, this
functionality may be overridden by setting `bind_quit` to an empty
expression to nop.
2. Interactive debugging via STDIN
The main application loop has been reworked to handle reading mepolang
from STDIN continually rather then as a one-shot operation on boot as
was previously the case with prior versions. This serves two purposes:
1) to allow interactive debugging by end-users and 2) this allows for
scripting mepo non-interactively / without user interaction.
Mepolang expressions are parsed on newlines characters and commands can
be batched in this way. To test this functionality simply start mepo
using the `-i` commandline flag (e.g. `mepo -i`) and type any mepolang
expression into the console. For example: `prefset_n crosshair_size 40;`.
The `-i` STDIN debugging functionality can also be used by piping STDIN
into mepo on boot as well such as via: `echo "prefset_n crosshair_size
40" | mepo -i`.
3. Async shellpipe, user location script, and pin editing script
The command previously known as `shellpipe` has been renamed to
`shellpipe_sync`, and a new command, `shellpipe_async` has been added
to allow for running asynchronous shell commands. The `shellpipe_async`
command functions identically to shellpipe, in receiving particular ENV
vars to expose, and running any resulting STDOUT as mepolang.
The asynchronous version of shellpipe, `shellpipe_async`, was primarily
built out to support two new scripts included in the default config which
utilize this functionality, which are described below, these scripts are:
1) a user pin location updating script and 2) a pin editing script.
Firstly, the newly added user pin location updating script,
`mepo_ui_menu_user_pin_updater.sh`, drops a pin on the map based on
the user's location. The user's location is obtained either by GPSd,
Geoclue2, or Mozilla Location Services (in that order, moving from one
method to the next if the prior is unavailable). Note, if desired GPSd
and Geoclue2 are now optional dependencies for this script; meanwhile the
fallback to MLS works based on curl/jq so no additional dependencies are
necessary for this fallback method. Ideally on the Pinephone and other
mobile devices, if setup, you will get the best results with GPSd. In my
testing on the Pinephone on postmarketOS, GPSd may need to be manually
enabled via `sudo /etc/gpsd/device-hook "" ACTIVATE`. Note: while in the
background the user's location pin will automatically update via a new
`bind_timer` command in the default config; you may also press `x` or
click on the new UI button labeled `Center` to run this same script in
a synchronous fashion and also reposition the map on the user's location.
Secondly, the newly added pin editing script, `mepo_ui_menu_pin_editor.sh`
script allows for adding, removing, and editing pins location and
metadata by the user. This script can be used both for filtering and
editing existing searches (from Nominatim, Overpass, etc.) and also for
saving/restoring bookmark pins. This functionality uses the save/restore
state of the preference system mentioned above in (1).
4. Misc features: Visual tile progress indicators, -ndc & -h CLI flags,
clipcopy/clippaste, and High-DPI cursor positioning bugfix
There are several miscellaneous but important features which have been
added in this release cycle which I'd like to mention in this section,
namely: visual tile progress indicators, two new CLI flags, the addition
of the `clipcopy`/`clippaste` mepolang commands, and the fix of a bug
related to high-DPI cursor positioning.
Firstly, tiles while loading now visually represent how much data has
been downloaded rather then just being a solid green color while loading
as with previous versions. With this change, the percentage and data in
kilobytes downloaded for each tile is shown and the background color
represents loading status where black is 0% loaded and white is 100%
and a gradient (of grays) indicates progress loading status.
Secondly, two new CLI flags have been added to the application. The
new `-ndc` flag allows you to run mepo without the 'default'
baked in mepolang configuration which automatically adds things such
keybindings/buttons/hooks for the bundled scripts and similar. And the
new `-h` flag is a simple commandline help flag which shows the program
usage for all of the existing commandline flags.
Thirdly, two new commands have been added for environment-independent
clipboard access. The `clipcopy` command copies the current map's
coordinates to the clipboard; meanwhile, the `clippaste` command relocates
the map given coordinates in the clipboard, or alternatively if what's
in the clipboard is not coordinates.. will run the clipboard contents
as mepolang. This is a nice way to debug one-off mepolang expressions.
The `clipcopy` command is bound in the default config to the hotkey `y`
and the `clippaste` command is bound in the default config to the hotkey
`Shift-y`.
Finally, as of the 2.0.22 release of SDL it seems there was a regression
with High-DPI environments such as Phosh (which scales 1.5x by default)
where cursor positioning functionality would sometimes break. The root
cause of this issue is that it seems unscaled cursor positioning was
being reported in mouse motion events; this caused clicking on pins
and UI buttons in high-DPI environments to not function properly. As
of this release, this bug has been resolved via using properly scaled
coordinates based on the application's scaled resolution proportion.
Fix issue causing commandline-based download mode (-d) to not work.
Fix a minor bug relating to undefined colors for TTF_RenderText_Blended
This release was focused on building out mobile support (for Phosh
and Sxmo primarily), which included switching to GPU-based rendering,
supporting HiDPI scaling, improving gesture support, handling UI-specific
quirks, and implementing clickable UI buttons support to complete the
4th Milestone (Wayland & Mobile Support). This release is built against
Zig 0.9.1. Major changes below:
1. GPU-based rendering & HiDPI support
In order to support mobile environments such as Sxmo (Sway/Wayland) and
Phosh, which both default to HiDPI scaling enabled at 2x, Mepo's default
SDL renderer has been switched to use GPU-based rendering (as opposed
to CPU/software-based rendering in 0.3 and earlier versions). GPU-based
rendering has better support for high DPI displays. No longer in the
underlying logic do we use the scaled window resolution but the true
pixel-based resolution based on getting the GL drawable size and scaling
coordinates similarly to the logical size.
The primary net effect users will notice is that resultingly,
on Phosh & Sxmo (Sway/Wayland), the UI now looks less blurry &
is high-quality/crisper. With GPU-based rendering now the default,
end users may also notice a slight speed improvement depending on
system specifications. Software-based rendering, while no longer the
default, is still supported via the new `-sw` commandline flag. This
can be helpful for debugging or for use on systems with low amounts of
GPU memory. In addition to the change to support GPU-based rendering,
we also now default to using the Wayland SDL videodriver rather then
the X videodriver (e.g. mepo no longer uses XWayland by default). Note,
this can be overriden via using the SDL_VIDEODRIVER env variable.
2. Sxmo & Phosh support and UI improvements
Sxmo (both X & Wayland) & Phosh support has been implemented.
In regards to Sxmo, prior versions had broken functionality in regards
to scaling, hotkeys/context menu, and overall polish; in this release
each of these points has been addressed. The default included scripts
have each been flagged with a new $HOTKEY variable (correlating to the
default bind_key config setting). Also an associated change in Sxmo's
codebase for the mepo contextmenu hook has been added based on these
$HOTKEY variables. As such Sxmo now generates its context menu (on
swipe down / volume up) identical to the menu presented by central menu
hold-click functionality (& in 0.4 the new UI menu button). Additionally,
quirks have been worked out to support SDL's text input system (which
is necessary for compatibility with wtype on Sway). There is one pending
change for Sxmo/dwm which has been merged into the sxmo-dwm codebase to
have mepo launch as tiled by default; this change will be included with
the next tagged version of sxmo-dwm which will be released in about a
weeks time from publishing these notes.
As for Phosh, this is the first release in which Mepo is now generally
usable in this environment; support involved several changes. Firstly,
the default backing menuing script now uses busctl on Phosh to launch
Squeekboard (the OSK) for text input. As such you no longer have to
manually open/close the keyboard when looking for POIs and similar.
Secondly, a desktop file and an exciting new icon (!) has been added.
As such, installing Mepo by default, you'll now see a nice new icon appear
on the launcher. Finally, Phosh UI-specific quirks have been resolved. A
performance issue has been examined which caused Mepo to operate very
slowly in Phoc while panning the map; this bug had to do with overhead
for updating the window title, which is now updated on a periodic
interval. Additionally the application's defaults have been setup so
that the OSK automatically hides on boot & during window management etc.
3. Gesture support improved: bind_gesture command & better defaults
Gesture support has been vastly improved and is now customizable based
on a new bind_gesture mepolang command. Using bind_gesture you can bind
1-n fingers for pinch & rotate gestures. By default 2-finger pinching
will zoom the map in & out; and 3-finger rotate will adjust the UI's
fontsize. Additionally gestures are now able to be disabled if desired
by the user - as gesture support is no longer hardcoded since all logic
goes through the new bind_gesture mepolang command.
With 2-finger pinch to zoom, delta tracking has been implemented
and as such you can only zoom at max 2 zoom levels in one continuous
gesture. This is to prevent behavior in prior releases where-in zooming
in and out was unbounded and thus it was easy to zoom to the max/min zoom
level. Defaults for gestures have been tested and are known to work well
on the Pinephone and the Motorola G4 Play (motorola-harpia). Additional
devices may require minor tweaking; however delta tracking should provide
a good baseline overall for cross-device support.
The last point to mention on gestures, is that while in previous versions
gestures often conflicted with panning.. causing the user to inadvertently
zoom in out while panning; this bug has been resolved. While using
two/three finger gestures, and double/triple tapping, the map is now fixed
in place and won't pan around; which feels more reliable in practice.
4. UI Buttons: bind_button command
Clickable graphical UI buttons have been implemented aligned to the
bottom right corner to provide easy to hit targets on mobile devices,
where keybindings are not available. Buttons can be arbitrarily added
via the new bind_button mepolang command and can execute arbitrary
mepolang code. As such if you want to create your own custom script
(say to reposition the map to a particular coordinate, search the map,
resolve bookmarks, or anything else you can think up); this is as simple
as placing the associated mepolang code in the bind_button command's
eval argument.
UI buttons have been added to default config to allow you to: launch
the central menu, relocate the map via Nominatim, search for POIs via
Nominatim or Overpass, and download all tiles in all zoom levels in
the current viewport. These buttons use the same scripts accessible via
keybindings and in the central menu. If you want a bare UI
or want to remove these buttons, this is feasible by using a custom
configuration since this functionality is completely built out through
the mepolang configuration system.
5. Misc UI improvements
A few additional miscellaneous polishing UI improvements not covered
above have been implemented which I'll mention here (note this is a
nonexhaustive list): 1) In the central menu, scripts labels have had
icons added. 2) The UI bottom bar now changes color while download tiles
(e.g. green for foreground downloading tiles or blue for background/queued
downloading tiles); the bar turns red while offline as was previously
implemented. 3) The Nominatim POI search script no longer provides
suggestions (which required an additional network call); this speed things
up substantially while launching this script. 4) A script has been added
to the central menu to drop a custom user pin arbitrarily on the map. And
5) STDERR debugging has been disabled by default to improve performance;
this debugging functionality is still available now through a new `-e`
commandline flag.