diff options
Diffstat (limited to 'README.org')
| -rw-r--r-- | README.org | 115 |
1 files changed, 103 insertions, 12 deletions
@@ -106,7 +106,9 @@ Simply use the keybinding you assigned, or run `M-x wttrin` to display the weath [[assets/location-menu.png]] -Choose one, or for a quick one-time weather check, type a new location and ⏎ . After the weather is displayed, you can press `a` to check another location, `g` to refresh, or `q` to quit. +Choose one, or for a quick one-time weather check, type a new location and ⏎ . After the weather is displayed, the footer shows two groups of keys. Keys that act on the view: `a` for another location, `g` to refresh, `q` to quit. Keys that act on your saved locations: `s` to save the shown location, `d` to make it your default, `r` to rename a saved location, and `x` to remove one. + +Pressing `d` sets =wttrin-favorite-location= to the location on screen and remembers it across restarts (via savehist), so the mode-line and future sessions follow it. Your default is also offered in the location list the next time you run =M-x wttrin=. Enable =savehist-mode= for the persistence to stick. (On a geolocation-detected buffer, `d` first prompts for a name and saves it — see Naming Locations.) If you're looking at cached data, a line below the weather art tells you how old it is (e.g., "Last updated: 2:30 PM (5 minutes ago)"). @@ -129,6 +131,24 @@ Most people will just want to add a bunch of cities to the location list. Howeve "41.89,12.48")) ;; GPS Coordinates for Rome #+end_src +*** Location Search History + +Locations you search successfully are remembered and offered as completion candidates the next time you run =M-x wttrin=, after your saved and default locations. Only successful lookups are saved, so typos and not-found locations never enter the history. Entries already offered elsewhere are not duplicated into the history: defaults, saved-location names (see Naming Locations), and raw =lat,lng= coordinates from geolocation are all kept out. + +History is capped at =wttrin-location-history-max= entries (default 20); the oldest fall off as new ones arrive. + +#+begin_src emacs-lisp + (setq wttrin-location-history-max 20) +#+end_src + +To persist the history across Emacs restarts, enable the built-in =savehist-mode=. Wttrin keeps its history variable registered automatically, even if you set =savehist-additional-variables= yourself, so there is nothing else to configure. Without =savehist-mode=, history lasts for the session only. + +#+begin_src emacs-lisp + (savehist-mode 1) +#+end_src + +Two commands manage the history: =M-x wttrin-remove-location-history= drops a single entry (with completion), and =M-x wttrin-clear-location-history= clears all of it. + *** Default Language Customizing 'wttrin-default-languages' allows users to tell Wttrin which language to request for the text it displays. For instance, this changes the language used for days of the week, periods of the day, and other related text. @@ -246,24 +266,20 @@ If a refresh fails, the emoji dims to gray and the tooltip tells you what went w *Note:* If the weather emoji appears as a monochrome symbol instead of a color icon, try setting `wttrin-mode-line-emoji-font` to match a color emoji font installed on your system. Use `M-x fc-list` or check your system fonts to see what's available. -*** Setting the Favorite Location from IP Geolocation -If you don't want to type your city by hand, wttrin can detect it for you. Two ways: +*** Weather for Your Current Location +If you don't want to type your city by hand, wttrin can detect it for you. -**Manual detection with confirmation:** +**From the picker (weather here, right now):** run =M-x wttrin= and pick the first entry, "Current location (detect)". wttrin looks up your city via IP geolocation and shows its weather. If the guess is wrong (VPN, mobile hotspot), the detected city is right there in the buffer header, so just open the picker again and type the correct city. -#+begin_src emacs-lisp - M-x wttrin-set-location-from-geolocation -#+end_src - -This looks up your city via IP geolocation, shows the detected location, and sets =wttrin-favorite-location= after you confirm. To make the setting persist across Emacs sessions, run =M-x customize-save-variable RET wttrin-favorite-location RET=, or add =(setq wttrin-favorite-location "Your City, State")= to your init file. +**Make the detected city your default:** in that weather buffer, press =d=. The detected city becomes =wttrin-favorite-location= (what the mode-line tracks). With =savehist-mode= on, the favorite persists across sessions automatically, since wttrin registers it with savehist. No =customize-save-variable= step is needed. -**Automatic detection on first use:** +**Always use my current location:** run =M-x wttrin-use-current-location=, or set the variable directly: #+begin_src emacs-lisp (setq wttrin-favorite-location t) #+end_src -When set to =t=, wttrin runs the geolocation lookup once on first use (when the mode-line first fetches, when the buffer cache first refreshes, etc.) and caches the result for the rest of the session. The lookup happens in the background, so Emacs startup isn't blocked. The first display tick shows a placeholder until the lookup returns; everything proceeds normally after that. +When set to =t=, wttrin runs the geolocation lookup once on first use (when the mode-line first fetches, when the buffer cache first refreshes, etc.) and caches the result for the rest of the session. The lookup happens in the background, so Emacs startup isn't blocked. The first display tick shows a placeholder until the lookup returns; everything proceeds normally after that. =M-x wttrin-use-current-location= is the labeled, confirmed way to choose this without typing the bare =t=. The default lookup provider is =ipapi.co=. Two alternatives ship with the package, both free and key-less: @@ -273,7 +289,82 @@ The default lookup provider is =ipapi.co=. Two alternatives ship with the packag (setq wttrin-geolocation-provider 'ipwhois) ;; ipwho.is (10k/month) #+end_src -*Note:* IP-based geolocation can be wrong when you are behind a VPN or using a mobile hotspot. The confirmation prompt lets you reject an inaccurate result. If you prefer, set =wttrin-favorite-location= directly to any city string that wttr.in understands. +*Note:* IP-based geolocation can be wrong when you are behind a VPN or using a mobile hotspot. If you prefer, set =wttrin-favorite-location= directly to any city string that wttr.in understands. + +**Higher accuracy via an external command:** IP geolocation only finds your network's exit point, which on a VPN or cellular hotspot can be the wrong city or state. For a more accurate fix, point =wttrin-geolocation-command= at a command that returns your coordinates as JSON: + +#+begin_src emacs-lisp + (setq wttrin-geolocation-command "your-location-script --json") +#+end_src + +The command runs asynchronously and must print a JSON object with numeric =lat= and =lng= keys. It may also include an =address= (or =label=) string; when present, wttrin shows it on a "Location:" line in the weather buffer so the resolved place is readable even though the weather is fetched by raw coordinates. Any other keys are ignored. For example: + +#+begin_src json + {"lat": 41.3222, "lng": -71.8113, "address": "Westerly, Rhode Island, USA"} +#+end_src + +wttrin queries wttr.in by the coordinates and lets it echo the place name in its own header. A command that scans nearby WiFi access points and looks them up (far more accurate than IP) is the typical source. The package ships no command and assumes nothing about your system, so this is inert until you set it. If the command is unset, exits non-zero, or prints no usable coordinates, wttrin falls back to the IP provider above. + +The resolved coordinates show in the header, with the readable place on the "Location:" line below: + +[[assets/geolocation.png]] + +Two ready-to-adapt example commands live in [[file:examples/geolocation/][examples/geolocation/]]: =google-geolocate.py= (Google Geolocation API, needs a key) and =apple-wps.py= (Apple's keyless WiFi positioning, which uses an undocumented endpoint — read its caveat). Both are Python 3 standard library, scan WiFi via =nmcli=, and print the JSON described above. See that directory's README for setup. + +The older =M-x wttrin-set-location-from-geolocation= command still works but is deprecated in favor of the picker entry above. + +**Turning geolocation off:** geolocation is on by default. To opt out — no "Current location" entry in the picker, no detection requests — set: + +#+begin_src emacs-lisp + (setq wttrin-geolocation-enabled nil) +#+end_src + +*** Naming Locations +A saved location has a friendly name and a separate query: =wttrin= shows the name in the picker, the buffer header, and the mode-line, but fetches weather for the query. That lets a precise query hide behind a readable name — "Superdome" rather than "1500 Sugar Bowl Dr, New Orleans". The query can be a city, a full address, or =lat,lng= coordinates. + +Set them in your init: + +#+begin_src emacs-lisp + (setq wttrin-saved-locations + '(("Superdome" . "1500 Sugar Bowl Dr, New Orleans") + ("Home" . "41.37,-71.83"))) +#+end_src + +Or build the directory interactively: + +- =M-x wttrin-save-location= — save the place in the current weather buffer (or a typed query) under a name. Saving an existing name updates its query. +- =M-x wttrin-rename-location= — rename an entry (refused if the new name is already taken). +- =M-x wttrin-remove-location= — remove an entry (asks to confirm). + +The directory persists across sessions with =savehist-mode= on (=wttrin= registers it), the same as your favorite and history. + +You can point =wttrin-favorite-location= at a saved name (e.g. ="Craig's House"=): the mode-line resolves it to the query for fetching but shows the name in the tooltip. + +When you pick "Current location (detect)" and press =d= to keep it, =wttrin= prompts for a name (prefilled with the detected address) and saves it as a named location, then makes it your default. Clear the field and press RET to keep the raw coordinates instead. Raw coordinates never clutter your history; only named places are remembered. + +*Privacy:* a saved query can be a home or work street address, kept in plaintext in your savehist file. With =wttrin-debug= on, the query and raw responses are also written to the debug log. =wttrin= does not encrypt or redact these, so save what you're comfortable storing in plain text. + +*** Theming the Faces +The text wttrin draws itself uses named faces, so themes and =M-x customize-face= can restyle it. (The weather art itself is colored by the ANSI codes wttr.in returns, not by these faces.) + +| Face | Styles | Default | +|------------------------------+--------------------------------------------+--------------------------| +| =wttrin-mode-line-stale= | the mode-line emoji when its data is stale | inherits =shadow= | +|------------------------------+--------------------------------------------+--------------------------| +| =wttrin-staleness-header= | the "Last updated:" and "Location:" lines | inherits =shadow= | +|------------------------------+--------------------------------------------+--------------------------| +| =wttrin-instructions= | the footer key labels | inherits =shadow= | +|------------------------------+--------------------------------------------+--------------------------| +| =wttrin-instructions-header= | the footer column headers | inherits =(bold shadow)= | +|------------------------------+--------------------------------------------+--------------------------| +| =wttrin-key= | the bracketed key chords ([a] [g] [q]) | inherits =bold= | + +Restyle them in your init file like any other face: + +#+begin_src emacs-lisp + (set-face-attribute 'wttrin-key nil :foreground "deep sky blue" :weight 'bold) + (set-face-attribute 'wttrin-staleness-header nil :slant 'italic) +#+end_src ** Debugging and Troubleshooting If something isn't working, debug mode logs every fetch, every display update, and every error. |