Hi all,
Welcome to the October update for Mepo covering the 1.0 release and
announcing the new documentation website at http://mepo.milesalan.com. You
can follow Mepo's development at http://sr.ht/~mil/mepo and do note
that release notes are also mirrored in the git annotated tags for
each release.
---------------------------------------------------------------------------
Contents:
1.0 Release Notes:
- Mepo scripts customizable ENV variables
- Plasma Mobile & Alternative environments support: Zenity & OSK detection
- Manpage & Markdown API documentation generation
- Documentation guides moved to mepo_website repository
Notes on Lomiri Support:
- Lomiri base SDL application functional via Wayland/Mir compatibility layer
- Issue with text input / scripts menuing on Lomiri
Mepo Documentation Website:
- New Website announced at: http://mepo.milesalan.com
- Demos Videos moved to Odysee
- New Demo video filmed for gestures
- New Screencasts for configuration & scripting
Packaging Status:
- Mepo 1.0 released in Alpine Edge
- Addition of findutils as a dependency and zenity as a menuing option
- Addition of a flatpak package on Flathub
Conclusion & Future Plans:
- Roadmap for NLnet NGI0 Discovery grant complete
- Future work will be driven based on ticket tracker
---------------------------------------------------------------------------
# 1.0 Release Notes
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.
---------------------------------------------------------------------------
# Notes on Lomiri Support
While Lomiri support was originally planned for this release cycle and
within the roadmap, unfortunately adding this support is infeasible at
the current moment due to platform incompatibilities around menuing
& text input / OSK. Mepo itself, the base SDL application does work
with Lomiri/Mir via the Mir/Wayland compatibility layer. You may pan
the map, download tiles, use multitouch gestures, etc. However, the
issue with full mepo support for Lomiri is that in terms of mepo's scripts
compatibility, I was unable to determine a workable solution for menuing /
text input compatible with Mir & the default OSK.
Menuing for mepo is built out in scripts which utilize menuing/text input
via {zenity,bemenu,dmenu}. For ordinary mobile and desktop X/Wayland
environments this user input method is ideal since it may be swapped out
depending on environment (and functions perfectly well on Phosh, Plasma
Mobile, Sxmo, desktop X, and desktop Wayland). Unfortunately however, for
Mir, it seems as if the Wayland protocols supported as of my testing on
Mir do not properly integrate with the OSK for Lomiri/Ubuntu Touch. The
net effect is the base SDL mepo application does function, menuing /
item selections additionally works via zenity for example for picking
an item in the central menu, but what does not work in Mir is text input
(for example typing a Nominatim search query to find). Launching zenity
with `--entry`, the OSK does not appear as it does automatically in
other environments like Phosh and Plasma Mobile; and further as far as
I can tell, within Lomiri there is no dbus interface or similar IPC to
launch the OSK through scripting as there is for Squeekboard on Phosh.
I don't think support in Lomiri would be impossible, as there may be a
workaround or possibly an upstream change to make.. however the effort
involved was underscoped, and as such official Lomiri support has been
dropped. Partial support via the Mir/Wayland compatibility layer is
still present regardless and it is possible still to use mepo with say
matchbox-keyboard, wvkbd, via a Wayland or X container solution like
libertine or similar, or simply via external scripting using mepo's `-i`
flag; but I do not consider this as mepo having full/official support
in the Lomiri environment.
---------------------------------------------------------------------------
# Mepo Documentation Website
A new documentation website has been developed as mentioned above which
hosts the completed user guide (covering UI usage, scripts, and more),
a guide to mepolang, an install guide, scripting guide, demos videos,
and more. This new documentation website is the 'single source of truth'
for all things mepo documentation going forward.
The website can be viewed at http://mepo.milesalan.com and
the sourcecode for the static site generation can be seen at
http://git.sr.ht/~mil/mepo_website.
The prior 0.4 release video is now hosted on Odysee and additionally
new screencast videos covering savestate, end-user scripting, and
configuration have been filmed as well. A new demo video covering
basic mobile UI gestures has also been filmed. The new demo videos
are available at mepo's website at: http://mepo.milesalan.com/demos.html
---------------------------------------------------------------------------
# Packaging Status
1. Mepo 1.0 released in Alpine Edge
For packaging, I've opened a merge request for upgrading
mepo to 1.0 on Alpine (and thus postmarketOS edge
downstream) yesterday which was merged this morning. See:
https://gitlab.alpinelinux.org/alpine/aports/-/merge_requests/39632
Mepo's alpine package has been split into several subpackages: mepo,
mepo-scripts-bemenu, mepo-scripts-dmenu, and mepo-scripts-zenity. The
base mepo package is just mepo without any provided scripts and thus no
runtime-dependencies; e.g. this is just the base SDL application. The
application may function in this state ideally with user-provided
configuration via the `-i` & `-ndc` commandline flags. Meanwhile,
mepo-scripts-{zenity,bemenu,dmenu} subpackages provide the default
scripts which provide good sensible user default to provide menuing for
things like Nominatim, Overpass, etc. Generally for users of Phosh,
Swmo, or desktop Wayland you should install `mepo-scripts-bemenu`,
users of Sxmo or desktop X should install `mepo-scripts-dmenu`, and
users of Plasma Mobile or alternative environments where basic windowing
compatibility is necessary (where a dock window may not work) should
install `mepo-scripts-zenity`.
I recommend packagers on other distributions to similarly provide
subpackages for zenity, bemenu, or dmenu for mepo-scripts; however if
a packager only wishes to provide a single menuing option or subpackage
support is not included in their distribution, I would recommend using
zenity as the most cross UI-environment friendly solution since zenity
creates a normal window rather then a dock window for menuing.
2. Addition of findutils as a dependency and zenity as a menuing option
Packagers should note that in this release cycle, for 1.0, as explained
in the previous section the user may install mepo-scripts with either
using zenity, bemenu, or dmenu. Additionally it should be noted GNU
findutils was added as a runtime dependency for mepo scripts which the
mepo_ui_helper_menu.sh script uses as the `-d` parameter for xargs is
necessary; distributions which use coreutils will have this by default,
distributions which use busybox should add findutils as a dependency
for mepo-scripts.
3. Addition of a flatpak Package on Flathub
Based on user request and in order to best support distributions
where Zig or other dependencies mepo relies on are not yet
packaged (such as Mobian and similar), a flatpak package has been
created and has been added to Flathub. This package may be seen at:
https://flathub.org/apps/details/com.milesalan.mepo
The flatpak package aims for the best out-of-the-box cross-environment
compatibility and, to this end, sets the default menuing program used
to be zenity rather then bemenu or dmenu by default. Users who wish to
use dmenu or bemenu with the flatpak may ofcourse set MEPO_MENUING to
`inputdmenu` or `inputbemenu` and play with the flatpak source (which
can be seen at https://github.com/flathub/com.milesalan.mepo/) as desired.
---------------------------------------------------------------------------
# Conclusion & Future Plans
With this update, 1.0 has been released, the Mepo website has been
launched, and the roadmap for the NLnet / NGI0 Discovery grant has been
completed! Work on mepo will continue, however new features will be
entirely community-driven/motivated as the roadmap has been completed.
There is still functionality that I think is quite important to add and
I would like to address in mepo such as pin layer performance (#26),
automatic software rendering detection (#43), and an OSM contribution
flow (#32); however future work will be driven by user input rather
then being driven by the now completed roadmap. The ticket system at
https://todo.sr.ht/~mil/mepo-tickets/ will be the primary mechanism for
tracking future work on mepo.
I want to thank everyone who has contributed to the project either through
patches, bugs, tickets, or just using mepo and providing feedback.
1.0 is just the start from my point of view and I look forward to
hearing from early supporters and welcoming new users just the same.
I encourage users to get in touch via IRC or the mailing list to discuss
feature ideas and ways in which we can make mepo even better. I hope
mepo proves useful and we can move mobile Linux forward into the future.
Cheers,
Miles