~mil/mepo

1.0 2 years ago

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.