~mil/mepo_website

0d7df887f9d6a2e0f71a0b6bbc264e96171517b8 — Miles Alan 2 months ago 8786d05
Userguide and installguide cleanup
3 files changed, 92 insertions(+), 63 deletions(-)

M src/assets/style.css
M src/pages/installguide.md
M src/pages/userguide.md
M src/assets/style.css => src/assets/style.css +7 -0
@@ 182,6 182,7 @@ p {
code {
  border: 1px dotted #888888;
  background: #e8e8e8;
  padding: 0 3px;
}
pre {
  border: 1px dotted #888888;


@@ 304,6 305,12 @@ hr {
  max-width: 300px;
}

.center-border {
  margin: 0 auto;
  display: block;
  border: 1px solid #000000;
}

/* Footer */

footer {

M src/pages/installguide.md => src/pages/installguide.md +28 -16
@@ 2,35 2,47 @@

<div class='toc'>
<ul>
<li><a href="#postmarketos-alpine-linux">PostmarketOS / Alpine Linux</a></li>
<li><a href="#distrobution-packages">Distrobution Packages</a></li>
<li><a href="#flatpak">Flatpak</a></li>
<li><a href="#notes-on-supported-ui-environments">Notes On Supported UI Environments</a></li>
</ul>
</div>

## PostmarketOS / Alpine Linux
## Distrobution Packages

To install on postmarketOS, depending on your targeted enviroment install
either `mepo-wayland`, `mepo-xorg`, or `mepo-framebuffer`. For Sxmo
or desktop X use mepo-xorg,  for Phosh, Swmo, sway, or desktop wayland
use mepo-wayland, or for framebuffer use mepo-framebuffer On Phosh,
a new icon will appear for Mepo, and in S{x,w}mo, mepo will appear in
the applications menu. To launch on desktop, you can directly run the
command `mepo`.
Below you will find links to the distrobutions on which Mepo has been
packaged and has known support. Generally using your distrobution's package
manager is the prefered install route. If you do not see your distrobution
in the below list, you may also install on alternative distrobutions using
the [officially maintained Flatpak](#flatpak).

Example install command:
**Supported distrobutions:**

```sh
apk add mepo-wayland
```
- [Alpine Edge & postmarketOS](https://pkgs.alpinelinux.org/package/edge/testing/aarch64/mepo)
  - Example install command for Phosh and Swmo: `apk add mepo-scripts-bemenu`
  - Example install command for Sxmo: `apk add mepo-scripts-dmenu`
  - Example install command for Plasma Mobile & alternative environments: `apk add mepo-scripts-zenity`
- [Arch Linux AUR](https://aur.archlinux.org/packages/mepo)
- [NixOS](https://github.com/NixOS/nixpkgs/tree/master/pkgs/applications/misc/mepo/default.nix)
- [NetBSD](https://pkgsrc.se/wip/mepo)

After installation, you may launch mepo by running the command `mepo`.
Alternatively, on environments such as Phosh and Plasma Mobile an icon
should appear in the launcher for Mepo based on the `.desktop` file.

---

## Flatpak

Mepo is available [as a flatpak on flathub](https://flathub.org/apps/details/com.milesalan.mepo),
to install, reference [your distrobutions guide for how to install Flatpak](https://flatpak.org/setup/)
and then run the below commands to add flathub, install, and run mepo:
Mepo is available [as a flatpak on flathub](https://flathub.org/apps/details/com.milesalan.mepo).
This is helpful for distrobutions where mepo has not been packaged yet. The
Flatpak package is officially maintained by Miles, the main developer of mepo.
Bugs related to the flatpak may be reported to the bug tracker or on the mailing list.

To install the flatpak, reference [your distrobutions guide for how to
install Flatpak](https://flatpak.org/setup/) to setup flatpak on your
machine and then run the below commands to add flathub, install the
flatpak, and run mepo:

```sh
flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo

M src/pages/userguide.md => src/pages/userguide.md +57 -47
@@ 110,7 110,7 @@ devices and similar is a primary usecase. Take note of the following shortcuts:
- **Three fingers rotate gesture counterclockwise**: Decrease UI fontsize
- **One finger hold:** Launch the [central menu](#the-central-menu)

<video class='demo-mobile' controls>
<video class='demo-mobile center-border' controls>
  <source src="https://media.lrdu.org/mepo_demos/mepo_demo_1.0_gestures.webm" type="video/webm">
  Your browser does not support the video tag.
</video> 


@@ 142,20 142,20 @@ may appear when using zenity:

Here's an explation of the options are available in the central menu:

- **Download: clear download queue** (w):  Clears the current download cache (background downloading of tiles).  
- **Download: custom region (interactive)** (q):  Queues the current bounding box / viewport of the map to be downloaded in the background. Interactive, in that user is prompted for the minimum and maximum zoom-level to be downloaded.  
- **Download: current bounding-box (non-interactive)** (Q):  Queues the current bounding box / viewport of the map to be downloaded in the background. Non-interactive, in that user is not prompted for zoom-level etc. All zoomlevels equal to and higher then the current zoom level are downloaded.  
- **Pin editor: Edit, save, and restore pin metadata** (f):  Provides comprehensive pin editing via interactive menuing, allowing the user to add and remove pins,as well as edit pin metadata. Uses the `filedump` command functionality to extract pin data. Script is designed to be used asychronously via `shellpipe_async`.  
- **Update: Fontsize** (Z):  Updates the fontsize of the UI prompting the user for the input size. Presents menuing prefilled between sizes 12 and 30.  
- **Update: Online/Offline toggle** (m):  Toggles the UI between offline and online mode (e.g. flipping the preference tile_cache_network).  
- **Update: Tilesource** (u):  Updates the tilesource for the map to pull from. Note %1$d, %2$d, and %3$d are used to indicate X, Y, and Z variables respectively. Presents menuing with presets for OSM Maps, Stamen, OpenCycleMap etc.  
- **Update: Zoom** (z):  Updates the zoom level based on users input. Presents menuing to  pick from zoom levels between 1 and 16.  
- **Relocate map: via search** (g):  Repositions the map latitude and longitude based on a Nominatim search query. Presents menuing to prompt user for input location and pick from Nominatim results.  
- **Route: via GraphHopper** (r):  Allows user to determine a route between two points via the publically accessible GraphHopper instance. Presents menuing to prompt user for origin and destination points. The cursor (e.g. the position of the mouse or on mobile the last clicked point - e.g. in case of click-hold functionality) and the centerpoint (where the crosshair is) may be used as origin or destination points as an alternative to named entries. Named entry searches use Nominatim to lookup the user input query. Resulting route is placed into pin group 1 as an ordered pin group wherein instructional pins show each direction in the route.  
- **Route: via OSM Relation / Public Transit** (R):  Drops pins on the map in pin group 1 for the given OSM relation ID. This can be used for general routing for any OSM relation (such as a subway, bus route, or similar). Presents menuing to prompt for the input OSM relation ID.  
- **POI Search: via Nominatim** (G):  Searches for points of intrest via the publically accessible Nominatim API based on the current viewport.  Presents menuing to prompt for input overpass query. Drops pins on the map for the resulting found points of intrest in pin group 0; purging any previous pins in in group 0.  
- **POI Search: via Overpass** (b):  Searches for points of intrest via the publically accessible Overpass API based on the current viewport.  Presents menuing to prompt for input overpass query. Drops pins on the map for the resulting found points of intrest in pin group 0; purging any previous pins in in group 0.  
- **Location Pin: Center on user location** (x):  Determinines the user location via GPSD, Geoclue, or Mozilla Location services. When provided with no argument runs the function `droppinactivateandcenter` which both drops a pin on the map and centers the map. Meanwhile the function `droppin` can be used in isolation to only drop a pin on the map. This script may be used synchronously or asynchronoulsly; within the default config `droppin` is used asynchronounously via `shellpipe_async`.  
- **[Download: clear download queue](https://git.sr.ht/~mil/mepo/tree/master/item/scripts/mepo_ui_menu_dbg_queueclear.sh)** (w):  Clears the current download cache (background downloading of tiles).  
- **[Download: custom region (interactive)](https://git.sr.ht/~mil/mepo/tree/master/item/scripts/mepo_ui_menu_dbg_queuedownloadinteractive.sh)** (q):  Queues the current bounding box / viewport of the map to be downloaded in the background. Interactive, in that user is prompted for the minimum and maximum zoom-level to be downloaded.  
- **[Download: current bounding-box (non-interactive)](https://git.sr.ht/~mil/mepo/tree/master/item/scripts/mepo_ui_menu_dbg_queuedownloadnoninteractive.sh)** (Q):  Queues the current bounding box / viewport of the map to be downloaded in the background. Non-interactive, in that user is not prompted for zoom-level etc. All zoomlevels equal to and higher then the current zoom level are downloaded.  
- **[Pin editor: Edit, save, and restore pin metadata](https://git.sr.ht/~mil/mepo/tree/master/item/scripts/mepo_ui_menu_pin_editor.sh)** (f):  Provides comprehensive pin editing via interactive menuing, allowing the user to add and remove pins,as well as edit pin metadata. Uses the `filedump` command functionality to extract pin data. Script is designed to be used asychronously via `shellpipe_async`.  
- **[Update: Fontsize](https://git.sr.ht/~mil/mepo/tree/master/item/scripts/mepo_ui_menu_pref_fontsize.sh)** (Z):  Updates the fontsize of the UI prompting the user for the input size. Presents menuing prefilled between sizes 12 and 30.  
- **[Update: Online/Offline toggle](https://git.sr.ht/~mil/mepo/tree/master/item/scripts/mepo_ui_menu_pref_network.sh)** (m):  Toggles the UI between offline and online mode (e.g. flipping the preference tile_cache_network).  
- **[Update: Tilesource](https://git.sr.ht/~mil/mepo/tree/master/item/scripts/mepo_ui_menu_pref_url.sh)** (u):  Updates the tilesource for the map to pull from. Note %1$d, %2$d, and %3$d are used to indicate X, Y, and Z variables respectively. Presents menuing with presets for OSM Maps, Stamen, OpenCycleMap etc.  
- **[Update: Zoom](https://git.sr.ht/~mil/mepo/tree/master/item/scripts/mepo_ui_menu_pref_zoom.sh)** (z):  Updates the zoom level based on users input. Presents menuing to  pick from zoom levels between 1 and 16.  
- **[Relocate map: via search](https://git.sr.ht/~mil/mepo/tree/master/item/scripts/mepo_ui_menu_reposition_nominatim.sh)** (g):  Repositions the map latitude and longitude based on a Nominatim search query. Presents menuing to prompt user for input location and pick from Nominatim results.  
- **[Route: via GraphHopper](https://git.sr.ht/~mil/mepo/tree/master/item/scripts/mepo_ui_menu_route_graphhopper.sh)** (r):  Allows user to determine a route between two points via the publically accessible GraphHopper instance. Presents menuing to prompt user for origin and destination points. The cursor (e.g. the position of the mouse or on mobile the last clicked point - e.g. in case of click-hold functionality) and the centerpoint (where the crosshair is) may be used as origin or destination points as an alternative to named entries. Named entry searches use Nominatim to lookup the user input query. Resulting route is placed into pin group 1 as an ordered pin group wherein instructional pins show each direction in the route.  
- **[Route: via OSM Relation / Public Transit](https://git.sr.ht/~mil/mepo/tree/master/item/scripts/mepo_ui_menu_route_overpassrelation.sh)** (R):  Drops pins on the map in pin group 1 for the given OSM relation ID. This can be used for general routing for any OSM relation (such as a subway, bus route, or similar). Presents menuing to prompt for the input OSM relation ID.  
- **[POI Search: via Nominatim](https://git.sr.ht/~mil/mepo/tree/master/item/scripts/mepo_ui_menu_search_nominatim.sh)** (G):  Searches for points of intrest via the publically accessible Nominatim API based on the current viewport.  Presents menuing to prompt for input overpass query. Drops pins on the map for the resulting found points of intrest in pin group 0; purging any previous pins in in group 0.  
- **[POI Search: via Overpass](https://git.sr.ht/~mil/mepo/tree/master/item/scripts/mepo_ui_menu_search_overpass.sh)** (b):  Searches for points of intrest via the publically accessible Overpass API based on the current viewport.  Presents menuing to prompt for input overpass query. Drops pins on the map for the resulting found points of intrest in pin group 0; purging any previous pins in in group 0.  
- **[Location Pin: Center on user location](https://git.sr.ht/~mil/mepo/tree/master/item/scripts/mepo_ui_menu_user_pin_updater.sh)** (x):  Determinines the user location via GPSD, Geoclue, or Mozilla Location services. When provided with no argument runs the function `droppinactivateandcenter` which both drops a pin on the map and centers the map. Meanwhile the function `droppin` can be used in isolation to only drop a pin on the map. This script may be used synchronously or asynchronoulsly; within the default config `droppin` is used asynchronounously via `shellpipe_async`.  

---



@@ 173,9 173,9 @@ As described above, **Nominatim** excels at **name based searches**. For
example if you wanted to find a restraunt called "Joe's Pizza" you could
type this directly into the Nominatim POI search script prompt. Or
similarly to find a starbucks, you could just type in "starbucks" in
the Nominatim prompt. Either select the Nm [UI button]() to launch
the Nominatim prompt. Either select the Nm [UI button](#the-ui-button-bar) to launch
a Nominatim POI search POI or select `POI Search: via Nominatim` from
the [central menu]().
the [central menu](#the-central-menu).

Meanwhile, **Overpass** is more powerful and suited then Nominatim for
POI searches **based on OSM tags**; for example if you wanted to find


@@ 185,9 185,11 @@ OSM tag `[amenity=cafe]`. This will find all OSM relations matching this
tag within the current bounding box. A number of prepopulated OSM tags
are available within the provided Overpass script; however if you want
to search any custom OSM tag, simply enter it and this will work just
the same. Either select the Overpass [UI button]() to launch
the same. Either select the Overpass [UI button](#the-ui-button-bar) to launch
a Overpass POI search POI or select `POI Search: via Overpass` from
the [central menu]().
the [central menu](#the-central-menu).

![https://media.lrdu.org/mepo_demos/mepo_demo_0.3_pois.png](https://media.lrdu.org/mepo_demos/mepo_demo_0.3_pois.png)

---



@@ 213,6 215,9 @@ indicated by the OSM relation ID on the map as an ordered pin group. Simply
enter the OSM relation ID or enter a labelled relation from the pre-selected
list. Relation IDs can be referenced on the [OSM Website](https://www.openstreetmap.org/).


![https://media.lrdu.org/mepo_demos/mepo_demo_0.3_routing.png](https://media.lrdu.org/mepo_demos/mepo_demo_0.3_routing.png)

---

## Repositioning the map


@@ 251,40 256,42 @@ arbitrary bookmark pin named foopin is placed on the map.
---

## Offline Usage
Mepo prioritizes offline usage as a first-class usecase. The mepo application
itself presents an SDL2 view of OSM tiles on the map along with a background
thread that interfaces with curl for downloading tiles. This background
downloading thread has the ability to be completly disabled through a
[mepolang preference]() named [tile_cache_network]() which you may read about
below. Do note however, `tile_cache_network` **does not** effect any scripts 
called.. if you wish to use scripts utilizing Nominatim or Overpass etc. 
offline for example for running your own instances locally, these ENV parameters
are customizable; see the [Overidable Script ENV variables]() section for more
details.

### Using the `tile_cache_network` parameter

If you have already used Mepo to download tiles, either interactively or
through the `mepo_dl.sh` script as described below; you may use Mepo entirely
offline by setting the preference `tile_cache_network` to `0`.
When the `tile_cache_network` property is 0, you'll see the bottom bar turn
red and `O:0`. This mode is helpful if you have bandwidth limitations (e.g. for your data plan
or similar) and want to make sure Mepo does not make **any** network requests. As mentioned
above this *does not* cover external scripts called through the `shellpipe` mechanism.

```sh
echo "prefset tile_cache_network 0;" | mepo -i
```

You'll see this noted noted in the download bar as `Offline`.

This mode is helpful if you have bandwidth limitations (e.g. for your data plan
or similar) and want to make sure Mepo does not make **any** network requests.
Note that `tile_cache_network` **does not** effect any scripts called, if you
wish to use script utilizing Nominatim or Overpass etc. offline, see the
[Overidable Script ENV variables]() section.


### Downloading tiles
### Downloading tiles non-interactively (via commandline)

It's a common use case to need to download an entire block / bounding box
of tiles while online before going offline. For example, say if you want
to use your phone with Mepo but are not sure you'll not have internet
access at your destination.

To facilitate downloading of tiles, Mepo features a non-interactive CLI
accessible through using the `-d` flag. This flag should be suffixed with
a list of 6 comma separate parameters (no whitespaces) in the form of
`lat_a,lon_a,lat_b,lon_b,zoom_min,zoom_max`. Zoom min and max can range
from 0-16. 

For example, to download a bounding box:
access at your destination. To facilitate downloading of tiles, you may
do this from the UI using the `Dl` button, but Mepo additionally features 
a non-interactive tile downloading CLI accessible through using the `-d` flag. 
This flag should be suffixed with a list of 6 comma separate parameters 
(no whitespaces) in the form of `lat_a,lon_a,lat_b,lon_b,zoom_min,zoom_max`. 
Zoom min and max can range from 0-16. For example, to download a bounding box:

```sh
mepo -d40.74946,-74.04673,40.818358,-73.88211,3,16


@@ 293,9 300,8 @@ mepo -d40.74946,-74.04673,40.818358,-73.88211,3,16
This may be a bit more involved then you would like to get, so as an
alternative you can use the provided `mepo_dl.sh` script which provides
a prompt-driven dialog which queries [Nominatim](https://nominatim.org)
to determine the bounding box to download and then feeds this into `mepo -d`.

Run this script as:
to determine the bounding box to download and then feeds 
this into `mepo -d`. Run this script as:

```sh
mepo_dl.sh


@@ 314,13 320,16 @@ scripts to use your local or custom instance is just a matter of updating
the appropriate ENV variables. All public endpoints & API keys which
are overridable by setting ENV variables are listed below respecitvely:

- **`MEPO_ENDPOINT_NOMINATIM_SEARCH`:** The Nominatim search endpoint to use
- **`MEPO_ENDPOINT_NOMINATIM_SEARCH`:** The [Nominatim](https://nominatim.org/) search endpoint to use
  - (Default: `https://nominatim.openstreetmap.org/search`)
- **`MEPO_ENDPOINT_GRAPHHOPPER_ROUTE`:** The Graphopper route endpoint to use
  - See [Nominatim Install Guide](https://nominatim.org/release-docs/latest/admin/Installation/) for details on using your own custom Nominatim instance offline.
- **`MEPO_ENDPOINT_GRAPHHOPPER_ROUTE`:** The [Graphopper](https://www.graphhopper.com/) route endpoint to use
  - (Default: `https://graphhopper.com/api/1/route`)
- **`MEPO_ENDPOINT_OVERPASS`:** The Overpass interpreter endpoint to use
  - See [GraphHopper Install Guide](https://github.com/graphhopper/graphhopper/blob/6.x/README.md#installation) for detail on using your own custom GraphHopper instance offline.
- **`MEPO_ENDPOINT_OVERPASS`:** The [Overpass](https://wiki.openstreetmap.org/wiki/Overpass_API) interpreter endpoint to use
  - (Default: `https://lz4.overpass-api.de/api/interpreter`)
- **`MEPO_ENDPOINT_MLS`:** The Mozilla Location Services geolocate endpoint to use
  - See [Overpass Install Guide](https://wiki.openstreetmap.org/wiki/Overpass_API/Installation) for details on using your own custom Overpass instance offline.
- **`MEPO_ENDPOINT_MLS`:** The [Mozilla Location Services](https://location.services.mozilla.com/) geolocate endpoint to use
  - (Default : `https://location.services.mozilla.com/v1/geolocate`)
- **`MEPO_ENDPOINT_OSM_WIKI_SPECIALPHRASES`:** The OSM wiki endpoint to retrieve special phrases from
  - (Default: `https://wiki.openstreetmap.org/wiki/Special:Export/Nominatim/Special_Phrases/EN`)


@@ 340,8 349,9 @@ are overridable by setting ENV variables are listed below respecitvely:
## Mepolang

Mepolang is Mepo's command language API for IPC that can be sent to its
process via STDIN continually. See the [Mepolang]() page and [scriting
guide]() for more information on mepolang usage.
process via STDIN continually. See the [Mepolang](/mepolang.html) page 
and [scripting guide](/scriptingguide.html) for more information on
mepolang usage.

---