emenel/doomemacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

merge: rewrite-docs

Browse source 
I've omitted docs/*.org from this merge, as there is still work left to
do there, but I am pushing the module docs early so folks can benefit
from the new docs sooner.
This commit is contained in:
Henrik Lissner 2022-08-03 03:23:34 +02:00
commit 1f8bf7accb
No known key found for this signature in database
GPG key ID: B60957CA074D39A3
179 changed files with 13125 additions and 8630 deletions
Download patch file Download diff file Expand all files Collapse all files

12
modules/app/README.org Normal file
View file

@ -0,0 +1,12 @@
# -*- mode: doom-docs-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* (but before [[doom-module:][:config]] modules).
* Frequently asked questions
/This category has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]

73
modules/app/calendar/README.org
View file

@ -1,34 +1,52 @@
#+TITLE: app/calendar
#+DATE: January 13, 2018
#+SINCE: v2.1
#+STARTUP: inlineimages
# -*- mode: doom-docs-org -*-
#+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 +59,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

118
modules/app/emms/README.org
View file

@ -1,71 +1,75 @@
#+TITLE: app/emms
#+DATE: March 6, 2021
#+SINCE: v3.0.0
#+STARTUP: inlineimages nofold
# -*- mode: doom-docs-org -*-
#+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:][<localleader> l]] Toggles whether or not the player repeats the playlist.
- [[kbd:][<localleader> m]] Mixes the playlist.
- [[kbd:][<localleader> i]] Insert specific song
- [[kbd:][<localleader> s]] Save the current playlist to a file
- [[kbd:][<localleader> 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

81
modules/app/everywhere/README.org
View file

@ -1,58 +1,73 @@
#+title: app/everywhere
#+date: February 7, 2021
#+since: v3.0
#+startup: inlineimages nofold
# -*- mode: doom-docs-org -*-
#+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

156
modules/app/irc/README.org
View file

@ -1,82 +1,82 @@
#+TITLE: app/irc
#+DATE: June 11, 2017
#+SINCE: v2.0.3
#+STARTUP: inlineimages
# -*- mode: doom-docs-org -*-
#+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:][<localleader> a]] | Switch to the next active buffer |
| ~circe-command-JOIN~ | [[kbd:][<localleader> j]] | Join a channel |
| ~+irc/send-message~ | [[kbd:][<localleader> m]] | Send a private message |
| ~circe-command-NAMES~ | [[kbd:][<localleader> n]] | List the names of the current channel |
| ~circe-command-PART~ | [[kbd:][<localleader> p]] | Part the current channel |
| ~+irc/quit~ | [[kbd:][<localleader> Q]] | Kill the current circe session and workgroup |
| ~circe-reconnect~ | [[kbd:][<localleader> 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 +86,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 +110,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 +122,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 +138,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 +160,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

147
modules/app/rss/README.org
View file

@ -1,92 +1,102 @@
#+TITLE: app/rss
#+DATE: May 12, 2020
#+SINCE: v2.0.9
#+STARTUP: inlineimages nofold
# -*- mode: doom-docs-org -*-
#+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 +116,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

158
modules/app/twitter/README.org
View file

@ -1,96 +1,102 @@
#+TITLE: app/twitter
#+DATE: October 11, 2019
#+SINCE: v2.0
#+STARTUP: inlineimages
# -*- mode: doom-docs-org -*-
#+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