From 5b354ae4f378f4c3884e3ef8f4601030b82d74bb Mon Sep 17 00:00:00 2001 From: Henrik Lissner Date: Sat, 16 Oct 2021 01:20:46 +0200 Subject: [PATCH] docs(:app): update READMEs to new format --- modules/app/README.org | 12 +-- modules/app/calendar/README.org | 74 +++++++++----- modules/app/emms/README.org | 119 +++++++++++----------- modules/app/everywhere/README.org | 82 ++++++++------- modules/app/irc/README.org | 157 +++++++++++++++-------------- modules/app/rss/README.org | 148 +++++++++++++++------------ modules/app/twitter/README.org | 159 ++++++++++++++++-------------- 7 files changed, 419 insertions(+), 332 deletions(-) diff --git a/modules/app/README.org b/modules/app/README.org index 62d4644af..5be6d7461 100644 --- a/modules/app/README.org +++ b/modules/app/README.org @@ -1,12 +1,10 @@ -← [[doom-module-index:][Back to module index]] ↙ [[doom-changelog-search:::app nil][Changelog]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]] +← [[doom-module-index:][Back to module index]] ↖ [[doom-module-source:app][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]] -------------------------------------------------------------------------------- -#+TITLE: :app -#+SUBTITLE: The ultimate code completion backend -#+CREATED: February 19, 2017 -#+SINCE: v21.12.0 -#+SETUPFILE: ../../docs/.setupfile.org +#+TITLE: :app +#+CREATED: February 19, 2017 +#+SINCE: 21.12.0 * Description Application modules are complex and opinionated modules that transform Emacs toward a specific purpose. They may have additional dependencies and *should be -loaded last*, before =:config= modules. +loaded last* (but before [[doom-module:][:config]] modules). diff --git a/modules/app/calendar/README.org b/modules/app/calendar/README.org index 19dc03203..4d24eaea6 100644 --- a/modules/app/calendar/README.org +++ b/modules/app/calendar/README.org @@ -1,34 +1,53 @@ -#+TITLE: app/calendar -#+DATE: January 13, 2018 -#+SINCE: v2.1 -#+STARTUP: inlineimages +← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::app calendar][Issues]] ↖ [[doom-module-source:app/calendar][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]] +-------------------------------------------------------------------------------- +#+TITLE: :app calendar +#+SUBTITLE: Watch your missed deadlines in real time +#+CREATED: January 13, 2018 +#+SINCE: 21.12.0 (#355) -* Table of Contents :TOC: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#packages][Packages]] -- [[#configuration][Configuration]] - - [[#changing-calendar-sources][Changing calendar sources]] - - [[#synchronizing-org-and-google-calendar][Synchronizing Org and Google Calendar]] - -* Description +* Description :unfold: This module adds a calendar view for Emacs, with org and google calendar sync support. -** Module Flags -This module provides no flags. +** Maintainers +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +/This module has no flags./ ** Packages -+ [[https://github.com/kiwanami/emacs-calfw][calfw]] -+ [[https://github.com/kiwanami/emacs-calfw][calfw-org]] -+ [[https://github.com/kidd/org-gcal.el][org-gcal]] +- [[doom-package:][calfw]] +- [[doom-package:][calfw-org]] +- [[doom-package:][org-gcal]] + +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module requires: +- A Google Calendar account. +- [[https://github.com/kidd/org-gcal.el#installation][An OAuth client ID]], for syncing said account with [[doom-package:][org-gcal]]. + +* TODO Usage +#+begin_quote + 🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* TODO Configuration +#+begin_quote + 🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Configuration ** Changing calendar sources By defining your own calendar commands, you can control what sources to pull calendar data from: - -#+BEGIN_SRC emacs-lisp +#+begin_src emacs-lisp (defun my-open-calendar () (interactive) (cfw:open-calendar-buffer @@ -41,10 +60,21 @@ calendar data from: (cfw:ical-create-source "Moon" "~/moon.ics" "Gray") ; ICS source1 (cfw:ical-create-source "gcal" "https://..../basic.ics" "IndianRed") ; google calendar ICS ))) -#+END_SRC +#+end_src The [[https://github.com/kiwanami/emacs-calfw][kiwanami/emacs-calfw]] project readme contains more examples. ** Synchronizing Org and Google Calendar The [[https://github.com/kidd/org-gcal.el][kidd/org-gcal.el]] project README contains more detailed instructions on how to link your calendar with Google calendars. + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + 🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/app/emms/README.org b/modules/app/emms/README.org index 6741690d7..dd7891d79 100644 --- a/modules/app/emms/README.org +++ b/modules/app/emms/README.org @@ -1,71 +1,76 @@ -#+TITLE: app/emms -#+DATE: March 6, 2021 -#+SINCE: v3.0.0 -#+STARTUP: inlineimages nofold +← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::app emms][Issues]] ↖ [[doom-module-source:app/emms][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]] +-------------------------------------------------------------------------------- +#+TITLE: :app emms +#+SUBTITLE: A media player for music no one's heard of +#+CREATED: March 06, 2021 +#+SINCE: 21.12.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] - - [[#arch-linux][Arch Linux]] - - [[#nixos][NixOS]] - - [[#ubuntu][Ubuntu]] -- [[#troubleshooting][Troubleshooting]] - - [[#new-music-files-not-showing-up-in-database][New music files not showing up in database]] -- [[#appendix][Appendix]] - - [[#keybinds][Keybinds]] - -* Description +* Description :unfold: This module enables Emacs to be used as a music player. It uses [[https://www.musicpd.org/][mpd]] as a backend server and [[https://musicpd.org/clients/mpc/][mpc]] to update your music database. ** Maintainers -This module has no dedicated maintainers. +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] -** Module Flags -This module provides no flags. +** Module flags +/This module has no flags./ -** Plugins -+ [[https://git.savannah.gnu.org/git/emms.git/][emms]] +** Packages +- [[doom-package:][emms]] -* Prerequisites -This module requires an active MPD server, the MPC utility, and a music library. +** Hacks +/No hacks documented for this module./ -** Arch Linux -#+BEGIN_SRC bash -pacman -S mpd mpc -#+END_SRC +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ -** NixOS -#+BEGIN_SRC nix -services.mpd.enable = true; -environment.systemPackages = [ pkgs.mpc_cli ]; -#+END_SRC +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] -** Ubuntu -#+BEGIN_SRC bash -apt install mpd mpc -#+END_SRC +This module requires: +- [[https://mpd.readthedocs.io/en/stable/user.html#installation][mpd]] (and a running mpd server) +- [[https://www.musicpd.org/clients/mpc/][mpc]] + +These should be available through your OS package manager. + +* TODO Usage +#+begin_quote + 🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +** Keybinds +- [[kbd:][ l]] Toggles whether or not the player repeats the playlist. +- [[kbd:][ m]] Mixes the playlist. +- [[kbd:][ i]] Insert specific song +- [[kbd:][ s]] Save the current playlist to a file +- [[kbd:][ p]] Insert playlist save into current playlist +- [[kbd:][g a]] Sort the browser by artists +- [[kbd:][g b]] Sort the browser by genre +- [[kbd:][X]] Stops the player +- [[kbd:][x]] pauses the player +- [[kbd:][D]] in the playlist window removes that item +- [[kbd:][C]] clears the playlist +- [[kbd:][>]] move five seconds forward in the current track +- [[kbd:][<]] Opposite five back +- [[kbd:][RET]] In browser adds the artist's songs to the playlist, in the playlist starts + playlist. + +* TODO Configuration +#+begin_quote + 🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote * Troubleshooting -** New music files not showing up in database -Try =M-x +emms/mpd-restart-music-daemon=. If that doesn't work restart emacs. +[[doom-report:][Report an issue?]] -* Appendix -** Keybinds -+ =SPC m l= Toggles whether or not the player repeats the playlist. -+ =SPC m m= Mixes the playlist. -+ =SPC m i= Insert specific song -+ =SPC m s= Save the current playlist to a file -+ =SPC m p= Insert playlist save into current playlist -+ =g a= Sort the browser by artists -+ =g b= Sort the browser by genre -+ =X= Stops the player -+ =x= pauses the player -+ =D= in the playlist window removes that item -+ =C= clears the playlist -+ =>= move five seconds forward in the current track -+ =<= Opposite five back -+ =RET= In browser adds the artist's songs to the playlist, in the playlist starts playlist. +** New music files not showing up in database +Try [[kbd:][M-x +emms/mpd-restart-music-daemon]] then restart emacs. + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + 🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/app/everywhere/README.org b/modules/app/everywhere/README.org index 2d75cf89b..457a533d1 100644 --- a/modules/app/everywhere/README.org +++ b/modules/app/everywhere/README.org @@ -1,58 +1,74 @@ -#+title: app/everywhere -#+date: February 7, 2021 -#+since: v3.0 -#+startup: inlineimages nofold +← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::app everywhere][Issues]] ↖ [[doom-module-source:app/everywhere][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]] +-------------------------------------------------------------------------------- +#+TITLE: :app everywhere +#+SUBTITLE: *leave* Emacs!? You must be joking +#+CREATED: February 07, 2021 +#+SINCE: 21.12.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] -- [[#configuration][Configuration]] - -* Description +* Description :unfold: This module adds system-wide popup Emacs windows for quick edits. ** Maintainers -+ [[https://github.com/tecosaur][@tecosaur]] +- [[doom-user:][@tecosaur]] -** Module Flags +[[doom-contrib-maintainer:][Become a maintainer?]] -This module provides no flags. +** Module flags +/This module has no flags./ -** Plugins -+ [[https://github.com/tecosaur/emacs-everywhere][emacs-everywhere]] +** Packages +- [[doom-package:][emacs-everywhere]] -* Prerequisites +** Hacks +/No hacks documented for this module./ -On Linux =xclip=, =xdotool=, =xprop=, and =xwininfo= are needed. +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ -On MacOS, Emacs must be allowed to "control your computer" under *Settings > Accessibility*. +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] -* Features +This module requires: +- *On Linux:* (these should be available through your OS package manager) + - =xclip= + - =xdotool= + - =xprop= + - =xwininfo= +- *On MacOS:* that Emacs is allowed to "control your computer" under *System + Preferences > Accessibility*. +* Usage To use this, invoke the =emacs-everywhere= executable. This can be done in two ways: -+ ~emacsclient --eval "(emacs-everywhere)"~ -+ ~doom everywhere~ ++ ~$ emacsclient --eval "(emacs-everywhere)"~ ++ ~$ doom everywhere~ It is recommended that you add a keybinding for this. From here, you can edit away to your hearts content in the created frame, then -return to the original window and paste the content with =C-c C-c= or =SPC q f=. -To exit without pasting, use =C-c C-k=. +return to the original window and paste the content with [[kbd:][C-c C-c]] or [[kbd:][SPC q f]]. To +exit without pasting, use [[kbd:][C-c C-k]]. * Configuration - -=emacs-everywhere= likes to guess if you triggered it from an application which +[[doom-package:][emacs-everywhere]] likes to guess if you triggered it from an application which supports markdown. Configure ~emacs-everywhere-markdown-windows~ and ~emacs-everywhere-markdown-apps~ to improve how accurate this is on your system. -By default, when markdown is detected, ~markdown-mode~ is used. It is possible to -instead use pandoc to convert the content to Org (and export to markdown when +By default, when markdown is detected, ~markdown-mode~ is used. It is possible +to instead use pandoc to convert the content to Org (and export to markdown when closing the frame) by setting ~emacs-everywhere-major-mode-function~ to -=#'org-mode=. +~#'org-mode~. -Most other behaviour is implemented as hooks on ~emacs-everywhere-init-hooks~. +Most other behavior is implemented as hooks on ~emacs-everywhere-init-hooks~. + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + 🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/app/irc/README.org b/modules/app/irc/README.org index 41e2983cc..952379d1e 100644 --- a/modules/app/irc/README.org +++ b/modules/app/irc/README.org @@ -1,82 +1,83 @@ -#+TITLE: app/irc -#+DATE: June 11, 2017 -#+SINCE: v2.0.3 -#+STARTUP: inlineimages +← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::app irc][Issues]] ↖ [[doom-module-source:app/irc][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]] +-------------------------------------------------------------------------------- +#+TITLE: :app irc +#+SUBTITLE: How neckbeards socialize +#+CREATED: June 11, 2017 +#+SINCE: 2.0.3 -* Table of Contents :TOC: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] - - [[#macos][macOS]] - - [[#debian--ubuntu][Debian / Ubuntu]] - - [[#arch-linux][Arch Linux]] - - [[#nixos][NixOS]] -- [[#features][Features]] - - [[#an-irc-client-in-emacs][An IRC Client in Emacs]] -- [[#configuration][Configuration]] - - [[#pass-the-unix-password-manager][Pass: the unix password manager]] - - [[#emacs-auth-source-api][Emacs' auth-source API]] -- [[#troubleshooting][Troubleshooting]] - -* Description +* Description :unfold: This module turns Emacs into an IRC client, capable of OS notifications. -** Module Flags -This module provides no flags. +** Maintainers +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] -** Plugins -+ [[https://github.com/jorgenschaefer/circe][circe]] -+ [[https://github.com/eqyiel/circe-notifications][circe-notifications]] +** Module flags +/This module has no flags./ -* Prerequisites -This module requires =gnutls= for secure IRC connections to work. +** Packages +- [[doom-package:][circe]] +- [[doom-package:][circe-notifications]] + +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module requires: +- [[https://www.gnutls.org/][GnuTLS]], for secure IRC connections to work. + +This should be available through your OS package manager. ** macOS -#+BEGIN_SRC sh +#+begin_src sh brew install gnutls -#+END_SRC +#+end_src ** Debian / Ubuntu -#+BEGIN_SRC sh +#+begin_src sh apt install gnutls-bin -#+END_SRC +#+end_src ** Arch Linux -#+BEGIN_SRC sh +#+begin_src sh pacman -S gnutls -#+END_SRC +#+end_src ** NixOS -#+BEGIN_SRC nix +#+begin_src nix environment.systemPackages = [ pkgs.gnutls ]; -#+END_SRC +#+end_src -* Features -** An IRC Client in Emacs -To connect to IRC you can invoke the ~=irc~ function using =M-x= or your own -custom keybinding. +* TODO Usage +#+begin_quote + 🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -| command | description | -|---------+-------------------------------------------| -| ~=irc~ | Connect to IRC and all configured servers | +To connect to IRC use ~M-x =irc~. -When in a circe buffer these keybindings will be available. +When in a circe buffer these keybindings will be available: +| command | key | description | +|-----------------------------+-----------------+----------------------------------------------| +| ~+irc/tracking-next-buffer~ | [[kbd:][ a]] | Switch to the next active buffer | +| ~circe-command-JOIN~ | [[kbd:][ j]] | Join a channel | +| ~+irc/send-message~ | [[kbd:][ m]] | Send a private message | +| ~circe-command-NAMES~ | [[kbd:][ n]] | List the names of the current channel | +| ~circe-command-PART~ | [[kbd:][ p]] | Part the current channel | +| ~+irc/quit~ | [[kbd:][ Q]] | Kill the current circe session and workgroup | +| ~circe-reconnect~ | [[kbd:][ R]] | Reconnect the current server | -| command | key | description | -|-----------------------------+-----------+----------------------------------------------| -| ~+irc/tracking-next-buffer~ | =SPC m a= | Switch to the next active buffer | -| ~circe-command-JOIN~ | =SPC m j= | Join a channel | -| ~+irc/send-message~ | =SPC m m= | Send a private message | -| ~circe-command-NAMES~ | =SPC m n= | List the names of the current channel | -| ~circe-command-PART~ | =SPC m p= | Part the current channel | -| ~+irc/quit~ | =SPC m Q= | Kill the current circe session and workgroup | -| ~circe-reconnect~ | =SPC m R= | Reconnect the current server | +* TODO Configuration +#+begin_quote + 🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Configuration -Use ~set-irc-server! SERVER PLIST~ to configure IRC servers. Its second argument (a plist) -takes the same arguments as ~circe-network-options~. - -#+BEGIN_SRC emacs-lisp :tangle no +Use ~set-irc-server! SERVER PLIST~ to configure IRC servers. Its second argument +(a plist) takes the same arguments as ~circe-network-options~: +#+begin_src emacs-lisp ;; if you omit =:host=, ~SERVER~ will be used instead. (after! circe (set-irc-server! "irc.libera.chat" @@ -86,20 +87,23 @@ takes the same arguments as ~circe-network-options~. :sasl-username "myusername" :sasl-password "mypassword" :channels ("#emacs")))) -#+END_SRC +#+end_src However, *it is a obviously a bad idea to store your password in plaintext,* so here are ways to avoid that: -** Pass: the unix password manager +** TODO Pass: the unix password manager +#+begin_quote + 🔨 /This section is outdated and needs to be rewritten./ [[doom-contrib-module:][Rewrite it?]] +#+end_quote + [[https://www.passwordstore.org/][Pass]] is my tool of choice. I use it to manage my passwords. If you activate the -[[../../../modules/tools/pass/README.org][:tools pass]] module you get an elisp API through which to access your -password store. +[[doom-module:][:tools pass]] module you get an elisp API through which to access your password +store. ~set-irc-server!~ accepts a plist can use functions instead of strings. ~+pass-get-user~ and ~+pass-get-secret~ can help here: - -#+BEGIN_SRC emacs-lisp :tangle no +#+begin_src emacs-lisp (set-irc-server! "irc.libera.chat" `(:tls t :port 6697 @@ -107,12 +111,11 @@ password store. :sasl-username ,(+pass-get-user "irc/libera.chat") :sasl-password ,(+pass-get-secret "irc/libera.chat") :channels ("#emacs"))) -#+END_SRC +#+end_src But wait, there's more! This stores your password in a public variable which could be accessed or appear in backtraces. Not good! So we go a step further: - -#+BEGIN_SRC emacs-lisp :tangle no +#+begin_src emacs-lisp (set-irc-server! "irc.libera.chat" `(:tls t :port 6697 @@ -120,12 +123,12 @@ could be accessed or appear in backtraces. Not good! So we go a step further: :sasl-username ,(+pass-get-user "irc/libera.chat") :sasl-password (lambda (&rest _) (+pass-get-secret "irc/libera.chat")) :channels ("#emacs"))) -#+END_SRC +#+end_src And you're good to go! -Note that =+pass-get-user= tries to find your username by looking for the fields -listed in =+pass-user-fields= (by default =login=, =user==, =username== and +Note that ~+pass-get-user~ tries to find your username by looking for the fields +listed in ~+pass-user-fields~ (by default =login=, =user==, =username== and =email=)=). An example configuration looks like #+begin_example @@ -136,8 +139,7 @@ username: myusername ** Emacs' auth-source API ~auth-source~ is built into Emacs. As suggested [[https://github.com/jorgenschaefer/circe/wiki/Configuration#safer-password-management][in the circe wiki]], you can store (and retrieve) encrypted passwords with it. - -#+BEGIN_SRC emacs-lisp :tangle no +#+begin_src emacs-lisp (setq auth-sources '("~/.authinfo.gpg")) (defun my-fetch-password (&rest params) @@ -159,6 +161,15 @@ username: myusername :nick "doom" :sasl-password my-nickserver-password :channels ("#emacs"))) -#+END_SRC +#+end_src * TODO Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + 🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/app/rss/README.org b/modules/app/rss/README.org index 2cd1f36e9..eee3f014b 100644 --- a/modules/app/rss/README.org +++ b/modules/app/rss/README.org @@ -1,92 +1,103 @@ -#+TITLE: app/rss -#+DATE: May 12, 2020 -#+SINCE: v2.0.9 -#+STARTUP: inlineimages nofold +← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::app rss][Issues]] ↖ [[doom-module-source:app/rss][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]] +-------------------------------------------------------------------------------- +#+TITLE: :app rss +#+SUBTITLE: An RSS reader that Google can't shut down +#+CREATED: May 12, 2020 +#+SINCE: 2.0.9 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] - - [[#hacks][Hacks]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] -- [[#configuration][Configuration]] - - [[#without-org][Without +org]] - - [[#with-org][With +org]] - - [[#keybindings][Keybindings]] - - [[#news-filtering][News filtering]] - - [[#automatically-updating-feed-when-opening-elfeed][Automatically updating feed when opening elfeed]] -- [[#troubleshooting][Troubleshooting]] - -* Description -+ Read RSS feeds in the comfort of DOOM (Emacs) +* Description :unfold: +Read RSS feeds in the comfort of Emacs. ** Maintainers -This module has no dedicated maintainers. +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] -** Module Flags -+ =+org= to enable ~elfeed-org~ to use ~org-directory/elfeed.org~ +** Module flags +- +org :: + Enable [[doom-package:][elfeed-org]], so you can configure your feeds with an org file + (={org-directory}/elfeed.org=) rather than Elisp. -** Plugins -+ [[https://github.com/skeeto/elfeed][elfeed]] -+ [[https://github.com/algernon/elfeed-goodies][elfeed-goodies]] -+ =+org= - + [[https://github.com/remyhonig/elfeed-org][elfeed-org]] +** Packages +- [[doom-package:][elfeed]] +- [[doom-package:][elfeed-goodies]] +- [[doom-package:][elfeed-org]] if [[doom-module:][+org]] ** Hacks -+ By default ~elfeed-search-filter~ is set to ~@2-weeks-ago~ and makes the last 2 weeks of entries visible. This needs to be set after elfeed has loaded like so in your ~config.el~ - #+begin_src elisp -(after! elfeed - (setq elfeed-search-filter "@1-month-ago +unread")) +- By default ~elfeed-search-filter~ is set to ~@2-weeks-ago~ and makes the last + 2 weeks of entries visible. This needs to be set after elfeed has loaded like + so in your =$DOOMDIR/config.el=: + #+begin_src emacs-lisp + (after! elfeed + (setq elfeed-search-filter "@1-month-ago +unread")) #+end_src -* Prerequisites -This module has no prerequisites. +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ -* Features -+ As there isn't currently binding for ~elfeed-update~ you can run it with ~M-x elfeed-update~ +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +/This module has no external requirements./ + +* TODO Usage +#+begin_quote + 🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +- As there isn't currently binding for ~elfeed-update~ you can run it with ~M-x + elfeed-update~ + +* TODO Configuration +#+begin_quote + 🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Configuration ** Without +org -When you don't want to use org mode to manage your elfeed feeds you can put your subscriptions to personal ~config.el~ file, ex: -#+BEGIN_SRC elisp +When you don't want to use org mode to manage your elfeed feeds you can put your +subscriptions in =$DOOMDIR/config.el=: +#+begin_src emacs-lisp (setq elfeed-feeds '("https://this-week-in-rust.org/rss.xml" "http://feeds.bbci.co.uk/news/rss.xml")) -#+END_SRC +#+end_src ** With +org -When using ~+org~ flag then configuration is easier. You can use ~org-mode~ to configure feeds to follow. -#+BEGIN_SRC org +When using ~+org~ flag then configuration is easier. You can use ~org-mode~ to +configure feeds to follow: +#+begin_src org ,* root :elfeed: ,** Programming :programming: ,*** [[https://this-week-in-rust.org/rss.xml][This Week in Rust]] :rust: ,** News :news: ,*** Top news :tops: ,**** http://feeds.bbci.co.uk/news/rss.xml -#+END_SRC -+ Root of ~elfeed-org~ needs to have ~:elfeed:~ tag. This is where ~elfeed-org~ starts to read. -+ You can have subheaders as in example ~:programming:~, and ~elfeed-org~ applies that tag to all subheader feeds, in example it adds it to ~This Week in Rust~. -+ You can "name" feeds as you please with ~org-mode~ ~org-insert-link~ (~C-c C-l~) and put name as you want into ~description~. -+ If you don't want to use ~org-directory/elfeed.org~ file you can specify it with ~(setq rmh-elfeed-org-files '("path/to/your/elfeed/file.org))~ +#+end_src +- Root of ~elfeed-org~ needs to have ~:elfeed:~ tag. This is where ~elfeed-org~ + starts to read. +- You can have subheaders as in example ~:programming:~, and ~elfeed-org~ + applies that tag to all subheader feeds, in example it adds it to ~This Week + in Rust~. +- You can "name" feeds as you please with ~org-mode~ ~org-insert-link~ ([[kbd:][C-c C-l]]) + and put name as you want into ~description~. +- If you don't want to use ~org-directory/elfeed.org~ file you can specify it + with ~(setq rmh-elfeed-org-files '("path/to/your/elfeed/file.org))~ ** Keybindings + General - | Key | Mode | Description | - |---------+--------------------+--------------------------------| - | =S-RET= | Elfeed-search-mode | Open link into browser | - | =RET= | Elfeed-search-mode | Open item | - | =s= | Elfeed-search-mode | Filter | - | =C-j= | Elfeed-show-mode | Move to next item | - | =C-k= | Elfeed-show-mode | Move to previous item | + | Key | Mode | Description | + |-------+--------------------+------------------------| + | [[kbd:][S-RET]] | elfeed-search-mode | Open link into browser | + | [[kbd:][RET]] | elfeed-search-mode | Open item | + | [[kbd:][s]] | elfeed-search-mode | Filter | + | [[kbd:][C-j]] | elfeed-show-mode | Move to next item | + | [[kbd:][C-k]] | elfeed-show-mode | Move to previous item | + If ~:editor evil +everywhere~ | Key | Description | |-----+-----------------------------| - | q | elfeed-kill-buffer | - | r | elfeed-search-update--force | - | g c | Copy link of current entry | + | [[kbd:][q]] | elfeed-kill-buffer | + | [[kbd:][r]] | elfeed-search-update--force | + | [[kbd:][g c]] | Copy link of current entry | ** News filtering + Time filtering @@ -106,9 +117,18 @@ When using ~+org~ flag then configuration is easier. You can use ~org-mode~ to c + Exclude ~!something~ ** Automatically updating feed when opening elfeed -Hook ~elfeed-update~ to ~elfeed-search-mode-hook~ -#+BEGIN_SRC elisp -(add-hook! 'elfeed-search-mode-hook 'elfeed-update) -#+END_SRC +Hook ~elfeed-update~ to ~elfeed-search-mode-hook~: +#+begin_src emacs-lisp +(add-hook 'elfeed-search-mode-hook #'elfeed-update) +#+end_src -* TODO Troubleshooting +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + 🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/app/twitter/README.org b/modules/app/twitter/README.org index 38d9694fe..83c2006b3 100644 --- a/modules/app/twitter/README.org +++ b/modules/app/twitter/README.org @@ -1,96 +1,103 @@ -#+TITLE: app/twitter -#+DATE: October 11, 2019 -#+SINCE: v2.0 -#+STARTUP: inlineimages +← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::app twitter][Issues]] ↖ [[doom-module-source:app/twitter][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]] +-------------------------------------------------------------------------------- +#+TITLE: :app twitter +#+SUBTITLE: Be superficial in plain text +#+CREATED: October 11, 2019 +#+SINCE: 2.0.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] - - [[#hacks][Hacks]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] -- [[#configuration][Configuration]] -- [[#troubleshooting][Troubleshooting]] -- [[#appendix][Appendix]] - - [[#commands--keybindings][Commands & Keybindings]] - -* Description +* Description :unfold: Enjoy twitter from emacs. -+ View various timelines side by side, e.g. user's timeline, home, etc. -+ Post new tweets -+ Send direct messages -+ Retweet -+ Follow and un-follow users -+ Favorite tweets +- View various timelines side by side, e.g. user's timeline, home, etc. +- Post new tweets +- Send direct messages +- Retweet +- Follow and un-follow users +- Favorite tweets -** Module Flags -This module provides no flags. +** Maintainers +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] -** Plugins -+ [[https://github.com/hayamiz/twittering-mode][twittering-mode]] -+ [[https://github.com/abo-abo/avy][avy]] +** Module flags +/This module has no flags./ -** TODO Hacks -{A list of internal modifications to included packages} +** Packages +- [[doom-package:][avy]] +- [[doom-package:][twittering-mode]] -* Prerequisites +** Hacks +/No hacks documented for this module./ -+ For SSL connection (required by Twitter's API), one of the followings is required: - + [[http://curl.haxx.se/][cURL]] - + [[http://www.gnu.org/software/wget/][GNU Wget]] - + [[http://www.openssl.org/][OpenSSL]] - + [[http://www.gnu.org/software/gnutls/][GnuTLS]] -+ [[http://www.gnupg.org/][GnuPG]] is required for keeping the OAuth token encrypted in local storage. -+ ~twittering-icon-mode~ converts retrieved icons into XPM by default. To - achieve this and for displaying icons in formats that are not supported by - Emacs as well as for resizing icon images, [[http://www.imagemagick.org/][ImageMagick]] is required. +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ - To build emacs with ImageMagick support the ~--with-imagemagick~ flag needs to - be passed to the ~configure~ script, e.g. ~./configure --with-imagemagick~. - For detailed instruction on how to build Emacs from source please refer to - [[https://git.savannah.gnu.org/cgit/emacs.git/tree/INSTALL][INSTALL]] in Emacs' savannah repository. -+ For keeping retrieved icons in local storage, [[http://www.gzip.org/][gzip]] is required. +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] -* TODO Features -An in-depth list of features, how to use them, and their dependencies. +This module requires: +- One of the following (for SSL connections; required by Twitter's API): + - [[http://curl.haxx.se/][cURL]] + - [[http://www.gnu.org/software/wget/][GNU Wget]] + - [[http://www.openssl.org/][OpenSSL]] + - [[http://www.gnu.org/software/gnutls/][GnuTLS]] +- [[http://www.gnupg.org/][GnuPG]], for encrypting the OAuth token, stored locally. +- [[http://www.gzip.org/][gzip]], for compressing retrieved profile pictures, +- [[http://www.imagemagick.org/][ImageMagick]], for displaying and resizing profile pictures. + + Build Emacs with ImageMagick support using the ~--with-imagemagick~ flag ([[https://git.savannah.gnu.org/cgit/emacs.git/tree/INSTALL][how + to build Emacs from source]]). + +* TODO Usage +#+begin_quote + 🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote * TODO Configuration -How to configure this module, including common problems and how to address them. +#+begin_quote + 🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Troubleshooting -Currently ~twittering-mode~ binds =SPC=, breaking its functionality as a leader -key. To work around this issue you may use =M-SPC= instead when in -~twittering-mode~. - -* Appendix ** Commands & Keybindings Here is a list of available commands and their default keybindings (defined in -[[./config.el][config.el]]). - +[[./config.el][config.el]]): | command | key / ex command | description | |---------------------+------------------+-------------------------------------------------------------| -| ~+twitter/quit~ | =q= | Close current window | -| ~+twitter/quit-all~ | =Q= | Close all twitter windows and buffers, and delete workspace | - -And when ~:editor evil +everywhere~ is active: +| ~+twitter/quit~ | [[kbd:][q]] | Close current window | +| ~+twitter/quit-all~ | [[kbd:][Q]] | Close all twitter windows and buffers, and delete workspace | +And when [[doom-module:][:editor evil +everywhere]] is active: | command | key / ex command | description | |--------------------------------------------------+------------------+------------------------------------------------------------------| -| ~twittering-favorite~ | =f= | Favorite/Like a tweet | -| ~twittering-unfavorite~ | =F= | Un-favorite/Un-like a tweet | -| ~twittering-follow~ | =C-f= | Follow user | -| ~twittering-unfollow~ | =C-F= | Un-follow user | -| ~twittering-delete-status~ | =d= | Delete a tweet | -| ~twittering-retweet~ | =r= | Retweet | -| ~twittering-toggle-or-retrieve-replied-statuses~ | =R= | Toggle or retrieve replies | -| ~twittering-update-status-interactive~ | =o= | Update tweets | -| ~+twitter/ace-link~ | =O= | Open some visible link from a ~twittering-mode~ buffer using ace | -| ~twittering-search~ | =/= | Search | -| ~twittering-goto-next-status~ | =J= | Go to next tweet | -| ~twittering-goto-previous-status~ | =K= | Go to previous tweet | -| ~twittering-goto-first-status~ | =gg= | Go to first tweet | -| ~twittering-goto-last-status~ | =G= | Go to last tweet | -| ~twittering-goto-next-status-of-user~ | =gj= | Go to next tweet of user | -| ~twittering-goto-previous-status-of-user)))~ | =gk= | Go to previous tweet of user | +| ~twittering-favorite~ | [[kbd:][f]] | Favorite/Like a tweet | +| ~twittering-unfavorite~ | [[kbd:][F]] | Un-favorite/Un-like a tweet | +| ~twittering-follow~ | [[kbd:][C-f]] | Follow user | +| ~twittering-unfollow~ | [[kbd:][C-F]] | Un-follow user | +| ~twittering-delete-status~ | [[kbd:][d]] | Delete a tweet | +| ~twittering-retweet~ | [[kbd:][r]] | Retweet | +| ~twittering-toggle-or-retrieve-replied-statuses~ | [[kbd:][R]] | Toggle or retrieve replies | +| ~twittering-update-status-interactive~ | [[kbd:][o]] | Update tweets | +| ~+twitter/ace-link~ | [[kbd:][O]] | Open some visible link from a ~twittering-mode~ buffer using ace | +| ~twittering-search~ | [[kbd:][/]] | Search | +| ~twittering-goto-next-status~ | [[kbd:][J]] | Go to next tweet | +| ~twittering-goto-previous-status~ | [[kbd:][K]] | Go to previous tweet | +| ~twittering-goto-first-status~ | [[kbd:][gg]] | Go to first tweet | +| ~twittering-goto-last-status~ | [[kbd:][G]] | Go to last tweet | +| ~twittering-goto-next-status-of-user~ | [[kbd:][gj]] | Go to next tweet of user | +| ~twittering-goto-previous-status-of-user)))~ | [[kbd:][gk]] | Go to previous tweet of user | + +* Troubleshooting +[[doom-report:][Report an issue?]] + +** ~twittering-mode~ overrides the [[kbd:][SPC]] key +Currently ~twittering-mode~ binds [[kbd:][SPC]], breaking its functionality as a leader +key for evil users. To work around this issue you may use [[kbd:][M-SPC]] instead. + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + 🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote +