diff options
| -rw-r--r-- | README.md | 94 | ||||
| -rw-r--r-- | README.org | 148 | ||||
| -rw-r--r-- | assets/location-menu.png | bin | 0 -> 40165 bytes | |||
| -rw-r--r-- | assets/made-for-emacs-badge.svg | 1 | ||||
| -rw-r--r-- | assets/wttrin.png | bin | 0 -> 187797 bytes | |||
| -rw-r--r-- | wttrin.png | bin | 224161 -> 0 bytes |
6 files changed, 149 insertions, 94 deletions
diff --git a/README.md b/README.md deleted file mode 100644 index 78282c3..0000000 --- a/README.md +++ /dev/null @@ -1,94 +0,0 @@ -# wttrin.el - -Emacs frontend for weather web service [wttr.in](https://wttr.in). - -This fork has a few minor improvements: -- It displays the date and time the weather was displayed. -- It allows for customizing the font and font height used to display. -- On location re-query, the original weather buffer is closed, reducing buffer clutter. -- The license has changed from the MIT license to the GNU General Public License Version 3. - -In addition, this fork applies the following patches (from bcbcarl/emacs-wttrin): -- [patch to request the return ascii instead of html](https://github.com/bcbcarl/emacs-wttrin/pull/18) from brannala -- [patch to select the unit system](https://github.com/bcbcarl/emacs-wttrin/pull/10) from RJTK -- [patch to use https instead of http](https://github.com/bcbcarl/emacs-wttrin/pull/15) from relrod - -All changes have been manually validated as working as of Monday, April 01, 2024 (not kidding). Automatic CI tests forthcoming. - -Bug reports and PRs are welcome. Enjoy! - -## USAGE - -Set a default cities list for completion: - -```elisp -(setq wttrin-default-cities '( "Berkeley, California" "Taipei, Taiwan" "Tainan, Taiwan")) -``` - -You can also specify default HTTP request Header for Accept-Language: - -```elisp -(setq wttrin-default-accept-language '("Accept-Language" . "zh-TW"))) -``` - -As well as the unit system, "m" for metric and "u" for USCS/imperial (the default is to choose based on your location): - -```elisp -(setq wttrin-unit-system "m") -``` - -If you want the weather to display in a monospaced font other than your default, you may specify it: - -```elisp -(setq wttrin-font-name "Hack Nerd Font Mono") -``` - -You can specify the font height as well: - -```elisp -(setq wttrin-font-height 120) -``` - -Then run `M-x wttrin` to display the weather. - -After the weather is displayed you may press `q` to quit the buffer or `g` to query the weather for another location. - - - -## INSTALLATION - -Since the versions on Melpa and Melpa-stable are broken and abandoned versions, you should avoid installing this package from those repositories. Instead you can install manually. - -- Clone this repository -- Add the following in your Emacs config file: - -```emacs-lisp -(add-to-list 'load-path "/path/to/the/cloned/emacs-wttrin") -(require 'wttrin) -... -``` - -or in use-package format: - -```emacs-lisp -(use-package wttrin - :load-path ""/path/to/the/cloned/emacs-wttrin" - ...) -``` - -Of if you are using straight, the recipe will be similar to: - -```emacs-lisp -(straight-use-package - '(wttrin :type git - :host github - :repo "bcbcarl/emacs-wttrin" - :fork (:host github - :repo "cjennings/emacs-wttrin"))) -``` - -I will contact the Melpa maintainers and update this package with a working version soon. - -## LICENSE - -GPL-v3 diff --git a/README.org b/README.org new file mode 100644 index 0000000..0ca076b --- /dev/null +++ b/README.org @@ -0,0 +1,148 @@ +* Wttrin for Emacs + +[[#installation][Installation]] | [[#usage][Usage]] | [[#customization][Customization]] | [[#history][History]] | [[#license][License]] + +[[https://www.gnu.org/software/emacs/][file:assets/made-for-emacs-badge.svg]] +[[https://melpa.org/#/wttrin][file:https://melpa.org/packages/wttrin-badge.svg]] +[[https://stable.melpa.org/#/wttrin][file:https://stable.melpa.org/packages/wttrin-badge.svg]] + +Wttrin is a simple Emacs frontend for Igor Chubin's popular Weather Web Service [[https://github.com/chubin/wttr.in][wttr.in]]. + +[[assets/wttrin.png]] + + +" /A change in the weather is sufficient to recreate the world and ourselves./ " +- /Marcel Proust, The Guermantes Way/ + +** Installation +*** Package Install and Use-Package +Wttrin is on [[https://melpa.org/][MELPA]] and [[https://stable.melpa.org/#/][MELPA Stable]], so I recommend adding a use-package declaration to your Emacs init file. Installing Wttrin, assigning a keybinding, and customizing the location list is as simple as adding the following code and evaluating it. + +#+begin_src emacs-lisp + (use-package wttrin + :ensure t + :commands (wttrin) + :bind ("C-c w" . wttrin) + :custom + (wttrin-default-locations '("Bondi Beach" "Taghazout" "Tamarindo" "Huntington Beach"))) +#+end_src + +With the cursor after the last closing parentheses, press "C-x C-e". Emacs will start the install, assign the keybinding, set the location list, and you'll be ready to go. + +*** Quelpa +If you typically use Quelpa to install the bleeding edge, here's what to put in your Emacs init: + +#+begin_src emacs-lisp + (quelpa '(wttrin + :fetcher github :repo "cjennings/emacs-wttrin")) + (define-key global-map (kbd "C-c w") 'wttrin) +#+end_src + +Wttrin is pulled to MELPA repositories regularly, so using Quelpa for Wttrin may provide no advantage over use-package. Regardless, Wttrin's main branch should always be stable. + +*** Straight +For the Elisp hackers using Straight for lockfiles or for easy hacking on bug fix PRs, you probably don't need me to tell you what to put in your Emacs init, but here's the code anyway. + +#+begin_src emacs-lisp + (straight-use-package + '(wttrin :type git :host github :repo "cjennings/emacs-wttrin")) +#+end_src + +*** Manual +Wttrin has a dependency on [[https://github.com/atomontage/xterm-color][xterm-color]] to colorize the weather display buffer. If you're manually installing Wttrin, you'll need to install the xterm-color package as well. + +1. Clone or download both the xterm-color and Wttrin repositories. + +#+begin_src sh + git clone https://github.com/atomontage/xterm-color.git + git clone https://github.com/cjennings/emacs-wttrin.git +#+end_src + +2. Add the following to your Emacs init file: + +#+begin_src elisp + (add-to-list 'load-path "/path/to/cloned/repo/emacs-wttrin") + (add-to-list 'load-path "/path/to/cloned/repo/xterm-color") + (require 'xterm-color) + (require 'wttrin) + (define-key global-map (kbd "C-c w") 'wttrin) +#+end_src + +3. Select those five statements and run M-x eval-region to load the package and set the keybinding. + +** Usage +Simply use the keybinding you assigned, or run `M-x wttrin` to display the weather. A list of locations will display. + +[[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 `g` to check another location or `q` to exit, just like it says in the buffer. + +** Customization +Wttrin can be customized using the built-in Emacs Customize interface. To do this, type M-x customize ⏎ wttrin ⏎ and use the UI. However, it's more portable and reproducible to keep the customizations in your init file, so do that. + +*** Default Location List + +Most people will just want to add a bunch of cities to the location list. However, you should know you can check the weather for places that aren't cities, so here's an example showing several ways to add locations to Wttrin. + +#+begin_src emacs-lisp + (setq wttrin-default-locations + '("Berkeley, CA" ;; City and State (to disambiguate) + "Wellington, New Zealand" ;; City and Country Name + "~Big+Ben" ;; The Landmark in London, not whomever you're thinking of + "70116" ;; Zip Code for the French Quarter, New Orleans + "BCN" ;; Airport Code for Barcelona + "41.89,12.48")) ;; GPS Coordinates for Rome +#+end_src + +*** 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. + +Wttrin's default is currently: "en-US,en;q=0.8,zh-CN;q=0.6,zh;q=0.4", + +This means Wttrin defaults to American English, then falls back to any other type of English, Simplified Chinese, then finally any other type of Chinese. Of course that doesn't even begin to account for everyone's use case, so here's what you need to know to customize this. + +Language codes usually follow the format of a primary language tag in lowercase (like "en" for English, "fr" for French, "zh" for Chinese), optionally with a region subtag in capitals (like "US" for United States or "CN" for China). If you use both, add a hyphen between them. You can enter just "en", but you may want to enter "en-GB" to avoid seeing how we trash the King's English on this side of the pond. + +To have Wttrin render in Traditional Chinese: + +#+begin_src emacs-lisp + (setq wttrin-default-languages '("Accept-Language" . "zh-TW")) +#+end_src + +And to have Wttrin render in French: + +#+begin_src emacs-lisp + (setq wttrin-default-languages '("Accept-Language" . "fr-FR")) +#+end_src + +Where to look up language codes? The IETF's BCP 47 official reference is online [[https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry][here]]. But those who were quick to open that link now know why I recommend another search interface: https://r12a.github.io/app-subtags/ + +*** Display Font and Size +The default font is "Liberation Mono" because it's libre and ubiquitous on Linux distributions. Don't worry, Emacs will find another monospaced font if that one's not installed. However, if you need to use your favorite monospaced font so Wttrin blends in with the rest of your Emacs Feng Shui, here you go: + +#+begin_src emacs-lisp + (setq wttrin-font-name "Hack Nerd Font Mono") +#+end_src + +You can change the font size by changing the font height. The default is 110. Note that Emacs uses the "canonical character height", which is 1/10th of a font point. For example, if you want a 12 point font size, you'd choose a font-height of 120. + +#+begin_src emacs-lisp + (setq wttrin-font-height 120) +#+end_src + +*** Unit System +Wttrin's default is to select the unit system appropriate for the location you query. Some may want the units they're familiar for the weather in all locations. + +#+begin_src emacs-lisp + (setq wttrin-unit-system "m") ;; for Metric units + (setq wttrin-unit-system "u") ;; for USCS/Imperial units + (setq wttrin-unit-system nil) ;; the default of using units appropriate for the queried location. +#+end_src + +** History +Wttrin was originally the work of Carl X. Su and Ono Hiroko. All credit and appreciation for the original idea and code is theirs, not mine. Over time the package stopped working due to the inevitablity of bit-rot and Emacs's own evolution. I loved using this package, so I adopted Wttrin to maintain and evolve for the Emacs community, and as thanks to the original authors. + +Please consider this repository as Wttrin's new home and I'll throw out a welcome mat. I am grateful for any and all bug reports, enhancement requests, and PRs, so feel free to send them my way. + +** License +GPL-v3.0 or later diff --git a/assets/location-menu.png b/assets/location-menu.png Binary files differnew file mode 100644 index 0000000..2421ae9 --- /dev/null +++ b/assets/location-menu.png diff --git a/assets/made-for-emacs-badge.svg b/assets/made-for-emacs-badge.svg new file mode 100644 index 0000000..5f9df38 --- /dev/null +++ b/assets/made-for-emacs-badge.svg @@ -0,0 +1 @@ +<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="151" height="20" role="img" aria-label="Made for: GNU Emacs"><title>Made for: GNU Emacs</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="151" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="76" height="20" fill="#555"/><rect x="76" width="75" height="20" fill="#7f5ab6"/><rect width="151" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><image x="5" y="3" width="14" height="14" xlink:href="data:image/svg+xml;base64,PHN2ZyBmaWxsPSIjZmFmYWZhIiByb2xlPSJpbWciIHZpZXdCb3g9IjAgMCAyNCAyNCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48dGl0bGU+R05VIEVtYWNzPC90aXRsZT48cGF0aCBkPSJNMTIsMjRDNS40NDgsMjQsMC4xMTgsMTguNjE3LDAuMTE4LDEyUzUuNDQ4LDAsMTIsMGM2LjU1MiwwLDExLjg4Miw1LjM4MywxMS44ODIsMTJTMTguNTUyLDI0LDEyLDI0eiBNMTIsMC42NjEgQzUuODEzLDAuNjYxLDAuNzc5LDUuNzQ4LDAuNzc5LDEyUzUuODEzLDIzLjMzOSwxMiwyMy4zMzljNi4xODcsMCwxMS4yMjEtNS4wODYsMTEuMjIxLTExLjMzOVMxOC4xODcsMC42NjEsMTIsMC42NjF6IE04LjAzLDIwLjE5NyBjMCwwLDAuOTc4LDAuMDY5LDIuMjM2LTAuMDQyYzAuNTEtMC4wNDUsMi40NDQtMC4yMzUsMy44OTEtMC41NTJjMCwwLDEuNzY0LTAuMzc3LDIuNzA3LTAuNzI1YzAuOTg3LTAuMzY0LDEuNTI0LTAuNjczLDEuNzY2LTEuMTEgYy0wLjAxMS0wLjA5LDAuMDc0LTAuNDA4LTAuMzgxLTAuNTk5Yy0xLjE2NC0wLjQ4OC0yLjUxNC0wLjQtNS4xODUtMC40NTdjLTIuOTYyLTAuMTAyLTMuOTQ4LTAuNTk4LTQuNDcyLTAuOTk3IGMtMC41MDMtMC40MDUtMC4yNS0xLjUyNiwxLjkwNy0yLjUxM2MxLjA4Ni0wLjUyNiw1LjM0NS0xLjQ5Niw1LjM0NS0xLjQ5NmMtMS40MzQtMC43MDktNC4xMDktMS45NTUtNC42NTktMi4yMjQgYy0wLjQ4Mi0wLjIzNi0xLjI1NC0wLjU5MS0xLjQyMS0xLjAyMWMtMC4xOS0wLjQxMywwLjQ0OC0wLjc2OCwwLjgwNC0wLjg3YzEuMTQ3LTAuMzMxLDIuNzY2LTAuNTM2LDQuMjQtMC41NiBjMC43NDEtMC4wMTIsMC44NjEtMC4wNTksMC44NjEtMC4wNTljMS4wMjItMC4xNywxLjY5NS0wLjg2OSwxLjQxNC0xLjk3NmMtMC4yNTItMS4xMy0xLjU3OS0xLjc5NS0yLjg0LTEuNTY1IGMtMS4xODgsMC4yMTctNC4wNSwxLjA0OC00LjA1LDEuMDQ4YzMuNTM5LTAuMDMxLDQuMTMxLDAuMDI4LDQuMzk1LDAuMzk4YzAuMTU2LDAuMjE4LTAuMDcxLDAuNTE4LTEuMDE1LDAuNjcyIGMtMS4wMjcsMC4xNjgtMy4xNjMsMC4zNy0zLjE2MywwLjM3Yy0yLjA0OSwwLjEyMi0zLjQ5MiwwLjEzLTMuOTI1LDEuMDQ2QzYuMjAyLDcuNTY0LDYuNzg3LDguMDk0LDcuMDQzLDguNDI1IGMxLjA4MiwxLjIwNCwyLjY0NiwxLjg1MywzLjY1MiwyLjMzMWMwLjM3OSwwLjE4LDEuNDksMC41MiwxLjQ5LDAuNTJjLTMuMjY1LTAuMTgtNS42MTksMC44MjMtNy4wMDEsMS45NzcgYy0xLjU2MiwxLjQ0NS0wLjg3MSwzLjE2OCwyLjMzLDQuMjI4YzEuODkxLDAuNjI2LDIuODI4LDAuOTIxLDUuNjQ4LDAuNjY3YzEuNjYxLTAuMDksMS45MjMtMC4wMzYsMS45MzksMC4xIGMwLjAyMywwLjE5Mi0xLjg0NSwwLjY2OS0yLjM1NSwwLjgxNkMxMS40NDgsMTkuNDM4LDguMDQ3LDIwLjE5Myw4LjAzLDIwLjE5N3oiLz48L3N2Zz4="/><text aria-hidden="true" x="475" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="490">Made for</text><text x="475" y="140" transform="scale(.1)" fill="#fff" textLength="490">Made for</text><text aria-hidden="true" x="1125" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="650">GNU Emacs</text><text x="1125" y="140" transform="scale(.1)" fill="#fff" textLength="650">GNU Emacs</text></g></svg>
\ No newline at end of file diff --git a/assets/wttrin.png b/assets/wttrin.png Binary files differnew file mode 100644 index 0000000..a81b4a5 --- /dev/null +++ b/assets/wttrin.png diff --git a/wttrin.png b/wttrin.png Binary files differdeleted file mode 100644 index 5a87e26..0000000 --- a/wttrin.png +++ /dev/null |
