4037 lines
174 KiB
Org Mode
4037 lines
174 KiB
Org Mode
#+title: Emacs setup for use with LaTeX, Org, and Python
|
||
#+author: Gerard Vermeulen
|
||
#+latex_class: article-local
|
||
#+latex_class_options: [11pt,a4paper,english,svgnames,tables]
|
||
#+macro: kbd (eval (by-backend-kbd-org-macro $1))
|
||
#+property: header-args:emacs-lisp :exports code :results silent :tangle init.el
|
||
#+property: header-args:org :tangle include.org
|
||
#+startup: showeverything
|
||
#+include: "include.org"
|
||
|
||
* Quick start
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:quick-start
|
||
:END:
|
||
|
||
Backup your =user-emacs-directory= (defaults often to =~/.emacs.d= on =Linux=,
|
||
=Unix=, or =Darwin=) directory and execute the commands in listing
|
||
[[lst:prepare-user-emacs-directory]]. After invoking Emacs interactively (in
|
||
interactive mode, neither in batch mode, nor in server mode), Emacs will ask you
|
||
to install a selected set of packages. Quit Emacs and invoke Emacs again.
|
||
|
||
#+caption[Prepare the user-emacs-directory]:
|
||
#+caption: Clone and initialize the user-emacs-directory.
|
||
#+name: lst:prepare-user-emacs-directory
|
||
#+begin_src shell :noeval :tangle no
|
||
cd ~
|
||
git clone ccdr@mercury.grenoble.cnrs.fr:SERVER/emacs.d.git .emacs.d
|
||
make --directory=.emacs.d init
|
||
emacs &
|
||
#+end_src
|
||
|
||
* Introduction
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:introduction
|
||
:END:
|
||
|
||
This Emacs setup aims to install automatically a minimal set of extension
|
||
packages that allows to handle my reports and presentations. The file format of
|
||
the reports is [[https://orgmode.org/][Org Mode]] plain text with [[https://www.python.org/][Python]] source code blocks and the file
|
||
format of the presentations is [[https://www.latex-project.org/][LaTeX]].
|
||
|
||
This [[info:org#Top][org]] file (more precisely the original [[info:org#Top][org]] source file of this file)
|
||
illustrates three methods in my work-flow:
|
||
1. How to tangle (or export) source blocks from [[info:org#Top][org]] files. This file contains
|
||
source blocks to produce the files =early-init.el=, =init.el=, =latexmkrc=, =org-store-link=, and =example.py= by tangling.
|
||
2. How to export [[info:org#Top][org]] files to other formats such as [[https://en.wikipedia.org/wiki/HTML][HTML]], [[https://www.latex-project.org/][LaTeX]], and [[https://en.wikipedia.org/wiki/PDF][PDF]].
|
||
3. How [[info:org#Hyperlinks][org hyperlinks (info)]] allow to link inside and outside [[info:org#Top][Org Mode]]: hover
|
||
over or click on the links to experiment.
|
||
|
||
The [[https://en.wikipedia.org/wiki/AUCTeX][AUCTeX - Aalborg University Center TeX]] extension package provides a
|
||
powerful [[https://en.wikipedia.org/wiki/Text-based_user_interface][Text-based User Interface (TUI)]] environment to edit the [[https://www.latex-project.org/][LaTeX]]
|
||
presentations.
|
||
|
||
The [[https://github.com/bdarcus/citar][citar]] extension package provides quick filtering and selecting of
|
||
bibliographic entries, and the option to run different commands on those
|
||
selections. [[https://github.com/bdarcus/citar][Citar]] requires [[info:org#Top][Org-9.5 (info)]], which is already part of Emacs-28.1.
|
||
[[https://github.com/bdarcus/citar][Citar]] exploits the enhancements of Emacs' builtin selection mechanism provided
|
||
by the extension packages [[https://github.com/minad/vertico][vertico]], [[https://github.com/oantolin/orderless][orderless]], [[https://github.com/oantolin/embark][embark]], [[https://github.com/minad/marginalia][marginalia]], and [[https://github.com/minad/consult][consult]].
|
||
The [[https://github.com/andras-simonyi/citeproc-el][citeproc]] extension package provides [[https://citationstyles.org/][CSL: citation style language]] processing
|
||
capabilities to [[https://github.com/bdarcus/citar][citar]] and [[https://orgmode.org/][Org Mode]]. [[https://github.com/citation-style-language/styles#readme][Citation style language: style repository]]
|
||
links to a curated repository of CSL styles.
|
||
|
||
The [[https://github.com/vedang/pdf-tools][pdf-tools]] extension package renders [[https://en.wikipedia.org/wiki/PDF][PDF]] file with the possibility to
|
||
annotate the file or to click on anchors in the [[https://en.wikipedia.org/wiki/PDF][PDF]] file that link back to the
|
||
original [[https://www.latex-project.org/][LaTeX]] file of the document. An example of my work-flow are the steps
|
||
to convert this [[info:org#Top][org]] file to [[https://en.wikipedia.org/wiki/PDF][PDF]] and to see the result with [[https://github.com/vedang/pdf-tools][pdf-tools]] in Emacs:
|
||
execute the commands ~pdf-tools-install~, ~org-babel-tangle~,
|
||
~org-latex-export-latex-to-latex~, and ~compile~. This sets up an infinite
|
||
[[https://www.latex-project.org/][LaTeX]] compilation loop to update and redisplay the [[https://en.wikipedia.org/wiki/PDF][PDF]] file after excution of
|
||
the ~org-latex-export-latex-to-latex~ command in this buffer.
|
||
|
||
Here follows a list of interesting Emacs configurations:
|
||
1. [[https://github.com/alhassy/emacs.d][Musa Al-hassy's configuration]] is an impressive example of producing the Emacs
|
||
initialization files and other files by tangling an [[info:org#Top][org]] file. His methodology
|
||
is impressive, as his [[https://alhassy.github.io/ElispCheatSheet/][Elisp Cheat Sheet]] and [[https://alhassy.github.io/org-special-block-extras/][org-special-block-extra package]]
|
||
show. To me, this is a configuration to admire, but his methodology is way
|
||
over my head.
|
||
2. [[https://github.com/oantolin/emacs-config][Omar Antolin Camarena's configuration]] exploits built-in packages, Omar's own
|
||
small packages, and large external packages. Omar is the author of [[https://github.com/oantolin/orderless][orderless]]
|
||
and [[https://github.com/oantolin/embark][embark]]. I have stolen his idea of using ~custom-set-variables~ instead
|
||
of the customize interface although that is [[https://www.masteringemacs.org/article/bad-emacs-advice][bad Emacs advice]] for new users.
|
||
3. [[https://gitlab.com/ambrevar/dotfiles][Pierre Neirhardt's configuration]] implements lazy loading without help of
|
||
external packages. I have stolen his approach of using lazy loading to
|
||
silently ignore the setup stanzas of uninstalled extension packages.
|
||
4. [[https://sachachua.com/dotemacs/][Sacha Chua's configuration]] is a practical example of producing the Emacs
|
||
initialization files by tangling an [[info:org#Top][org]] file. It gives me the impression
|
||
that she is a very practical person trying to achieve her goals by the most
|
||
efficient means. I have stolen her idea of using [[https://github.com/quelpa/quelpa][quelpa]] to install packages
|
||
from any source.
|
||
5. [[https://github.com/purcell/emacs.d][Steve Purcell's configuration]] is well organized, a showcase of readable code,
|
||
as well helpful commit and issue histories. See for instance the discussion
|
||
on [[https://github.com/purcell/emacs.d/issues/778][the correctness of order of company candidates in Emacs lisp mode]].
|
||
|
||
Here follows a list of links on how to use Emacs and Elisp:
|
||
1. [[https://www.youtube.com/watch?v=lkIicfzPBys][A guided tour of Emacs]] is a link to a video tour pointing how [[info:emacs#Buffers][buffers (info)]],
|
||
[[info:emacs#Dired][dired (info)]], [[info:emacs#Help][documentation (info)]], [[info:elisp#Top][elisp (info)]], [[info:elisp#Debugging][elisp debugging (info)]],
|
||
[[info:eshell#Top][eshell (info)]], and [[info:emacs#Keyboard Macros][keyboard macros (info)]] turn Emacs in an powerful coding
|
||
and editing environment.
|
||
2. [[https://www.youtube.com/watch?v=6ZWp05OW1c0][Emergency Emacs]] is a link to a video on fundamental editing features and
|
||
principles with focus on [[info:ediff#Top][ediff (info)]], [[info:emacs#Undo][undo (info)]], [[info:emacs#Moving Point][moving point (info)]],
|
||
[[info:emacs#Erasing][erasing (info)]], and [[info:emacs#Dynamic Abbrevs][dynamic abbreviations (info)]].
|
||
2. [[https://endlessparentheses.com/][Endless Parentheses]] is a blog with many mindblowing code snippets.
|
||
3. [[https://protesilaos.com/codelog/2022-01-31-learning-emacs/][Learning Emacs and Elisp]] is a link to a video tutorial with a transcript on
|
||
the best approach to learn Emacs and Elisp.
|
||
4. [[https://www.masteringemacs.org/][Mastering Emacs]] is a link to a blog with many interesting posts that promotes
|
||
a book on how to become a proficient Emacs user.
|
||
|
||
* [[info:emacs#Early Init File][Early Init File (info)]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:early-init-file
|
||
:END:
|
||
|
||
Try to load [[https://github.com/emacscollective/no-littering][no-littering]] as early as possible, since it helps to keep
|
||
=~/.emacs.d= clean.
|
||
|
||
#+caption[Tangle the early-init-file]:
|
||
#+caption: Tangle the early-init-file.
|
||
#+name: lst:tangle-early-init-file
|
||
#+begin_src emacs-lisp :tangle early-init.el
|
||
;;; early-init.el --- user early-init file -*- lexical-binding: t -*-
|
||
;;; Commentary:
|
||
;;; Code:
|
||
(setq load-prefer-newer t)
|
||
|
||
(require 'no-littering nil 'noerror)
|
||
|
||
(provide 'early-init)
|
||
;; Emacs looks for "Local variables:" after the last "?\n?\f".
|
||
|
||
;; Local Variables:
|
||
;; indent-tabs-mode: nil
|
||
;; End:
|
||
;;; earl-init.el ends here
|
||
#+end_src
|
||
|
||
In order to get help in understanding the code block above in a buffer showing
|
||
the original [[info:org#Top][Org]] source file, type {{{kbd(C-c C-c)}}} after moving
|
||
point (or cursor) to one of the items of the list:
|
||
1. src_emacs-lisp{(describe-variable #'load-prefer-newer t)}
|
||
2. src_emacs-lisp{(apropos-library "no-littering")}
|
||
3. src_emacs-lisp{(find-function #'hack-local-variables)}
|
||
to execute the code between the curly braces for access to help. This shows
|
||
that *Emacs is a self-documenting editor.*
|
||
|
||
* [[info:emacs#Init File][Init File (info)]] header
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:init-file-header
|
||
:END:
|
||
|
||
The =user-init-file= header requires =cl-lib= and customizes Emacs variables.
|
||
It consists of three parts in listing [[lst:1st-custom-set-variables-call]],
|
||
[[lst:2nd-custom-set-variables-call]], and [[lst:3rd-custom-set-variables-call]] in
|
||
order to limit the length of the listings for exporting to LaTeX.
|
||
|
||
The [[info:elisp#Quoting][quoting (info)]] and the [[info:elisp#Backquote][backquote (info)]] pages explain how to understand the
|
||
~'~ (quote), ~`~ (backquote), ~,~ (substitute) and ~@,~ (splice) in the
|
||
~custom-set-variables~ function calls in listing
|
||
[[lst:1st-custom-set-variables-call]], [[lst:2nd-custom-set-variables-call]], and
|
||
[[lst:3rd-custom-set-variables-call]]. A tutorial of how to use those reader macros
|
||
is the [[https://mullikine.github.io/posts/macro-tutorial/][didactic emacs-lisp macro example]].
|
||
|
||
The [[info:emacs#Init File][init file (info)]] does not load the ~custom-file~ as [[info:emacs#Saving Customizations][saving customizations
|
||
(info)]] recommends because of the ~custom-set-variables~ function calls.
|
||
|
||
#+caption[Customize the first set of Emacs variables]:
|
||
#+caption: Customize the first set of Emacs variables.
|
||
#+name: lst:1st-custom-set-variables-call
|
||
#+begin_src emacs-lisp
|
||
;;; init.el --- user init file -*- lexical-binding: t -*-
|
||
;;; Commentary:
|
||
;;; Code:
|
||
(require 'cl-lib)
|
||
|
||
(custom-set-variables
|
||
'(after-save-hook #'executable-make-buffer-file-executable-if-script-p)
|
||
'(column-number-mode t)
|
||
'(cursor-type 'box)
|
||
`(custom-file ,(locate-user-emacs-file "custom.el"))
|
||
'(epg-pinentry-mode 'loopback)
|
||
'(global-hl-line-mode t)
|
||
'(global-hl-line-sticky-flag t)
|
||
'(history-delete-duplicates t)
|
||
'(history-length 500)
|
||
'(indent-tabs-mode nil)
|
||
'(inhibit-startup-buffer-menu t)
|
||
'(inhibit-startup-screen t)
|
||
'(initial-buffer-choice t)
|
||
'(initial-scratch-message "")
|
||
`(insert-directory-program ,(or (executable-find "gls")
|
||
(executable-find "ls")))
|
||
'(kill-ring-max 300))
|
||
#+end_src
|
||
|
||
#+caption[Customize the second set of Emacs variables]:
|
||
#+caption: Customize the second set of Emacs variables.
|
||
#+name: lst:2nd-custom-set-variables-call
|
||
#+begin_src emacs-lisp
|
||
(custom-set-variables
|
||
'(package-archives '(("gnu" . "https://elpa.gnu.org/packages/")
|
||
("gnu-devel" . "https://elpa.gnu.org/devel/")
|
||
("melpa" . "https://melpa.org/packages/")
|
||
("nongnu" . "https://elpa.nongnu.org/nongnu/")))
|
||
;; Pin packages to GNU ELPA for info or stability.
|
||
'(package-pinned-packages '((auctex . "gnu")
|
||
(compat . "gnu")
|
||
(consult . "gnu")
|
||
(marginalia . "gnu")
|
||
(org . "gnu-devel")
|
||
(queue . "gnu")
|
||
(rainbow-mode . "gnu")
|
||
(spinner . "gnu")
|
||
(xr . "gnu")
|
||
(vertico . "gnu")))
|
||
'(package-selected-packages
|
||
'(async ; asynchroneous processing
|
||
auctex ; Aalborg University Center TeX
|
||
citar ; bibliography handling
|
||
company ; complete anything
|
||
consult ; consult completing-read
|
||
eglot ; Emacs polyGLOT LSP client
|
||
embark ; act on any buffer selection
|
||
htmlize ; convert buffer contents to HTML
|
||
magit ; Git Text-based User Interface
|
||
marginalia ; minibuffer margin notes
|
||
no-littering ; keep `user-emacs-directory' clean
|
||
orderless ; Emacs completion style
|
||
org-menu ; transient menu for org-mode
|
||
quelpa ; install Emacs packages from source
|
||
vertico ; VERTical Interactive Completion
|
||
wgrep ; open a writable grep buffer
|
||
xr))) ; undo rx to grok regular expressions
|
||
#+end_src
|
||
|
||
#+caption[Customize the third set of Emacs variables]:
|
||
#+caption: Customize the third set of Emacs variables.
|
||
#+name: lst:3rd-custom-set-variables-call
|
||
#+begin_src emacs-lisp
|
||
(custom-set-variables
|
||
'(recentf-mode t)
|
||
'(save-place-mode t)
|
||
'(scroll-bar-mode nil)
|
||
'(tab-always-indent 'complete)
|
||
'(tab-width 8)
|
||
'(tool-bar-mode nil)
|
||
'(url-cookie-trusted-urls nil)
|
||
'(url-cookie-untrusted-urls '(".*"))
|
||
'(use-dialog-box nil)
|
||
'(view-read-only t))
|
||
|
||
(when (version< "28.0" emacs-version)
|
||
(custom-set-variables
|
||
'(mode-line-compact 'long)
|
||
'(next-error-message-highlight t)
|
||
'(use-short-answers t)))
|
||
|
||
(when (eq system-type 'darwin)
|
||
(custom-set-variables
|
||
'(ns-alternate-modifier nil)
|
||
'(ns-command-modifier 'meta)
|
||
'(ns-right-command-modifier 'super)))
|
||
|
||
(when (eq window-system 'ns)
|
||
(add-to-list 'initial-frame-alist '(height . 51))
|
||
(add-to-list 'initial-frame-alist '(width . 180)))
|
||
#+end_src
|
||
|
||
* [[info:emacs#Package Installation][Install the selected packages (info)]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:install-selected-packages
|
||
:END:
|
||
|
||
[[info:emacs#Package Installation][Emacs installs packages]] from archives on the internet. This setup uses three
|
||
archives:
|
||
1. The [[https://elpa.gnu.org/][GNU Emacs Lisp Package Archive]]
|
||
2. The [[https://elpa.nongnu.org/][NonGNU Emacs Lisp Package Archive]].
|
||
3. The [[https://melpa.org/#/][Milkypostman's Emacs Lisp Package Archive (MELPA)]].
|
||
In addition, the [[https://github.com/quelpa/quelpa][quelpa]] tool allows to fetch code from any source and build a
|
||
package on your computer before installation. The code in listing
|
||
[[lst:install-selected-packages]] assumes that the package system is in a *virgin*
|
||
state if the package [[https://github.com/emacscollective/no-littering][no-littering]] is not present:
|
||
1. It installs and loads [[https://github.com/emacscollective/no-littering][no-littering]] after ensuring refreshing of the
|
||
contents of available packages.
|
||
2. It installs [[https://elpa.gnu.org/devel/org.html][Org (GNU-devel ELPA archive)]] early to shadow the built-in package
|
||
while preventing collisions between the snapshot and built-in packages.
|
||
3. It ensures installation of [[https://github.com/quelpa/quelpa][quelpa]] before ensuring installation of [[https://github.com/sheijk/org-menu#readme][org-menu]].
|
||
4. It calls src_emacs-lisp{(package-install-selected-packages)} to check the
|
||
installation status of all packages in
|
||
src_emacs-lisp{package-selected-packages} and to install the missing packages
|
||
after the user has agreed to its prompt.
|
||
5. It defines a function to ensure the installation of packages in other source
|
||
blocks. This allows skipping installation in sections with a =:noexport:=
|
||
tag by disallowing tangling.
|
||
In case of normal Emacs usage, src_emacs-lisp{(package-list-packages)} refreshes
|
||
the contents of packages and allows to update packages to the latest version.
|
||
|
||
#+caption[Install the selected packages]:
|
||
#+caption: Install the selected packages.
|
||
#+name: lst:install-selected-packages
|
||
#+begin_src emacs-lisp
|
||
(unless noninteractive
|
||
(unless (require 'no-littering nil 'noerror)
|
||
(unless (bound-and-true-p package-archive-contents)
|
||
(package-refresh-contents))
|
||
;; Install and require `no-littering'.
|
||
(package-install 'no-littering)
|
||
(require 'no-littering)
|
||
;; Shadow built-in `org' by installing `org'.
|
||
;; https://emacs.stackexchange.com/a/45939 answers
|
||
;; "How to shadow automatically a built-in package by installing it?"
|
||
(defun shadow-builtin-by-install (pkg)
|
||
(when-let ((desc (cadr (assq pkg package-archive-contents))))
|
||
(package-install desc 'dont-select)))
|
||
(shadow-builtin-by-install 'org)
|
||
;; Install `quelpa'.
|
||
(unless (package-installed-p 'quelpa)
|
||
(package-install 'quelpa))
|
||
;; Install `org-menu'.
|
||
(when (fboundp 'quelpa)
|
||
(unless (package-installed-p 'org-menu)
|
||
;; Neither GNU ELPA, nor MELPA provide this package.
|
||
(quelpa '(org-menu :repo "sheijk/org-menu" :fetcher github))))
|
||
;; Install the selected packages.
|
||
(package-install-selected-packages)))
|
||
|
||
(defun ensure-package-installation (&rest packages)
|
||
"Ensure installation of all packages in PACKAGES."
|
||
(let ((ok t))
|
||
(dolist (package packages)
|
||
(unless (package-installed-p package)
|
||
(package-install package))
|
||
(if (package-installed-p package)
|
||
(when (bound-and-true-p package-selected-packages)
|
||
(cl-pushnew package package-selected-packages))
|
||
(setq ok nil)))
|
||
ok))
|
||
#+end_src
|
||
|
||
* [[info:emacs#Faces][Text faces or look (info)]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:text-faces-or-look
|
||
:END:
|
||
|
||
Section [[#sec:text-faces-or-styles][text faces or styles]] tells that this setup does not use theming.
|
||
However, in order to improve visibility, it relies on:
|
||
1. Tweaking the background color of the already loaded =region= face as in
|
||
listing [[lst:tweak-region-face-background-color]].
|
||
2. Toggling between a dark and light background by means of
|
||
src_emacs-lisp{(invert-default-face)} in listing [[lst:invert-default-face]].
|
||
3. Shadowing the definition of faces before loading as in listing
|
||
[[lst:tweak-org-block-face]] and [[lst:tweak-sh-heredoc-face]]. The last item in the
|
||
page on [[https://orgmode.org/worg/org-contrib/babel/examples/fontify-src-code-blocks.html#org5c4406f][fontifying Org mode source code blocks]] describes this method.
|
||
|
||
#+caption[Tweak the background color of the =region= face in =faces.el=]:
|
||
#+caption: Tweak the background color of the =region= face in =faces.el=.
|
||
#+name: lst:tweak-region-face-background-color
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'emacs
|
||
(defun tweak-region-face-background-color ()
|
||
(when (featurep 'gtk)
|
||
(set-face-attribute
|
||
'region nil
|
||
:background (cdr (assoc (face-attribute 'default :background)
|
||
'(("white" . "LightGoldenrod2")
|
||
("black" . "blue3")))))))
|
||
|
||
(tweak-region-face-background-color))
|
||
#+end_src
|
||
|
||
#+caption[Implement =invert-default-face=]:
|
||
#+caption: Implement =invert-default-face=.
|
||
#+name: lst:invert-default-face
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'emacs
|
||
(defun invert-default-face ()
|
||
"Invert the default face."
|
||
(interactive)
|
||
(invert-face 'default)
|
||
(tweak-region-face-background-color)))
|
||
#+end_src
|
||
|
||
#+caption[Improve the visibility of the =org-block= face in =org-faces.el=]:
|
||
#+caption: Improve the visibility of the =org-block= face in =org-faces.el=.
|
||
#+name: lst:tweak-org-block-face
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'emacs
|
||
;; Shadow the definition in org-faces.el:
|
||
(defface org-block
|
||
;; https://emacs.stackexchange.com/a/9604 answers:
|
||
;; How to override a defined face for light and dark backgrounds?
|
||
`((((background dark))
|
||
:inherit (fixed-pitch)
|
||
,@(and (>= emacs-major-version 27) '(:extend t))
|
||
:background "#444444")
|
||
(t
|
||
:inherit (fixed-pitch)
|
||
,@(and (>= emacs-major-version 27) '(:extend t))
|
||
:background "#FFFFD0"))
|
||
"My face used for text inside various blocks.
|
||
|
||
It is always used for source blocks. You can refine what face
|
||
should be used depending on the source block language by setting,
|
||
`org-src-block-faces', which takes precedence.
|
||
|
||
When `org-fontify-quote-and-verse-blocks' is not nil, text inside
|
||
verse and quote blocks are fontified using the `org-verse' and
|
||
`org-quote' faces, which inherit from `org-block'."))
|
||
#+end_src
|
||
|
||
#+caption[Improve the visibility of the =sh-heredoc= face in =sh-script.el=]:
|
||
#+caption: Improve the visibility of the =sh-heredoc= face in =sh-script.el=.
|
||
#+name: lst:tweak-sh-heredoc-face
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'emacs
|
||
;; Shadow the definition in sh-script.el:
|
||
(defface sh-heredoc
|
||
'((((class color) (background dark))
|
||
(:foreground "yellow"))
|
||
(((class color) (background light))
|
||
(:foreground "magenta"))
|
||
(t
|
||
(:weight bold)))
|
||
"My face to show a here-document."))
|
||
#+end_src
|
||
|
||
* [[info:elisp#Advising Functions][Advising Functions (info)]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:advising-function
|
||
:END:
|
||
|
||
#+caption[Tools for advising functions]:
|
||
#+caption: Tools for advising functions.
|
||
#+name: lst:advising-tools
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'emacs
|
||
(defun toggle-advice (symbol where function &optional props)
|
||
"Toggle between states after `advice-remove' and `advice-add'."
|
||
(let ((how "%s `%s' advice `%s' %s `%s'"))
|
||
(if (advice-member-p function symbol)
|
||
(progn
|
||
(message how "Removal of" where function "from" symbol)
|
||
(advice-remove symbol function))
|
||
(message how "Addition of" where function "to" symbol)
|
||
(advice-add symbol where function props)))))
|
||
#+end_src
|
||
|
||
* [[info:emacs#Dired][Dired: directory editor as file manager (info)]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:file-manager
|
||
:END:
|
||
|
||
[[info:emacs#Dired][Dired (info)]] and the [[https://github.com/ranger/ranger#readme][ranger]] file manager offer similar capabilities for copying,
|
||
deleting, opening, renaming, and viewing files and directories, but the
|
||
integration of [[info:emacs#Dired][dired (info)]] in Emacs is obviously much better than the
|
||
integration of [[https://github.com/ranger/ranger#readme][ranger]] in Emacs.
|
||
|
||
For instance, this setup allows to insert an =org-mode= link to an poorly
|
||
identified file containing a specific image into an =org-mode= buffer by means
|
||
of the facilities of [[info:emacs#Dired][dired (info)]] as follows:
|
||
1. Type {{{kbd(C-x d)}}} to open the directory containing the pooly identified
|
||
file with the specific image in a =dired-mode= buffer.
|
||
2. Start searching for the specific image by navigating to the name of any image
|
||
file.
|
||
3. Type {{{kbd(v)}}} to switch to view the file in an =image-mode= buffer.
|
||
4. In the =image-mode= buffer, continue searching for the specific image by
|
||
typing:
|
||
- {{{kbd(n)}}} to view the next image in the =dired-mode= buffer,
|
||
- {{{kbd(p)}}} to view the previous image in the =dired-mode= buffer, and
|
||
- {{{kbd(q)}}} to quit the =image-mode= buffer and to go back to the =dired-mode= buffer.
|
||
5. After finding the specific image, use {{{kbd(C-c l)}}} in the =image-mode=
|
||
buffer or the =dired-mode= buffer to store the =org-link=.
|
||
6. Switch to the =org-mode= buffer and use {{{kbd(C-c C-l)}}} to insert the =org-link= into the buffer.
|
||
|
||
Listing [[lst:customize-dired]] makes the directory editor sort entries
|
||
alphabetically after grouping the directories before grouping the files by
|
||
extension.
|
||
|
||
#+caption[Customize =dired=]:
|
||
#+caption: Customize =dired=.
|
||
#+name: lst:customize-dired
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'dired
|
||
(custom-set-variables
|
||
'(dired-dwim-target t)
|
||
;; | switch | action |
|
||
;; |--------+----------------------------------------|
|
||
;; | -a | also list hidden entries |
|
||
;; | -l | use a long listing format |
|
||
;; | -X | sort alphabetically by entry extension |
|
||
;; | -G | skip long listing format group names |
|
||
;; | -1 | list one entry per line |
|
||
'(dired-listing-switches "-alGX1 --group-directories-first")
|
||
'(dired-recursive-copies 'always)
|
||
'(dired-recursive-deletes 'always)))
|
||
|
||
(with-eval-after-load 'files
|
||
(custom-set-variables
|
||
;; Ensure the use of `GNU-ls' from `coreutils' on darwin.
|
||
'(insert-directory-program (or (executable-find "gls")
|
||
(executable-find "ls")))))
|
||
|
||
(with-eval-after-load 'wdired
|
||
(custom-set-variables
|
||
'(wdired-allow-to-change-permissions t)))
|
||
#+end_src
|
||
|
||
Listing [[lst:extra-dired-key-bindings]] adds new key bindings to =dired-mode-map= to:
|
||
1. Open files with the [[https://en.wikipedia.org/wiki/Eww_(web_browser)][Emacs Web Wowser]] inside Emacs.
|
||
2. Let [[https://en.wikipedia.org/wiki/Rsync][rsync]] copy marked files outside Emacs to a local or remote directory.
|
||
The link [[https://truongtx.me/tmtxt-dired-async.html][asynchoronous execution library for Emacs Dired]] is the original source
|
||
for the idea of using [[https://en.wikipedia.org/wiki/Rsync][rsync]] and the blog articles [[https://oremacs.com/2016/02/24/dired-rsync/][using rsync in dired]] and
|
||
[[https://vxlabs.com/2018/03/30/asynchronous-rsync-with-emacs-dired-and-tramp/][asynchronous rsync with Emacs, dired and tramp]] are vivid recommendations written
|
||
by experienced Emacs users.
|
||
|
||
#+caption[Extra =dired= key bindings]:
|
||
#+caption: Extra =dired= key bindings.
|
||
#+name: lst:extra-dired-key-bindings
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'dired
|
||
(defun dired-eww-open-file ()
|
||
"In Dired, open the regular file named on this line with eww"
|
||
(interactive)
|
||
(let ((file (dired-get-file-for-visit)))
|
||
(if (file-regular-p file)
|
||
(eww-open-file file)
|
||
(error "Eww rejects `%s', since it is not a regular file" file))))
|
||
|
||
;; https://truongtx.me/tmtxt-dired-async.html
|
||
(defun dired-rsync (target)
|
||
"Copy marked files with `rsync' to TARGET directory."
|
||
(interactive
|
||
(list (expand-file-name
|
||
(read-file-name "Rsync to:" (dired-dwim-target-directory)))))
|
||
;; Store all marked files into the `files' list and intialize
|
||
;; the `rsync-command'.
|
||
(let ((files (dired-get-marked-files nil current-prefix-arg))
|
||
(rsync-command "rsync -av --progress "))
|
||
;; Add all marked files as arguments to the `rsync-command'.
|
||
(dolist (file files)
|
||
(setq rsync-command
|
||
(concat rsync-command
|
||
(if (string-match "^/ssh:\\(.*\\)$" file)
|
||
(format " -e ssh %s" (match-string 1 file))
|
||
(shell-quote-argument file)) " ")))
|
||
;; Append the destination directory to the `rsync-command'.
|
||
(setq rsync-command
|
||
(concat rsync-command
|
||
(if (string-match "^/ssh:\\(.*\\)$" target)
|
||
(format " -e ssh %s" (match-string 1 target))
|
||
(shell-quote-argument target))))
|
||
;; Run the async shell command.
|
||
(async-shell-command rsync-command)
|
||
;; Finally, switch to that window.
|
||
(other-window 1)))
|
||
|
||
(define-key dired-mode-map (kbd "E") #'dired-eww-open-file)
|
||
(define-key dired-mode-map (kbd "Y") #'dired-rsync))
|
||
#+end_src
|
||
|
||
* [[info:elisp#Processes][Processes (info)]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:processes
|
||
:END:
|
||
|
||
Listing [[lst:process-utilities]] defines a function to run a (command-line) program
|
||
with arguments and to obtain a list with its numeric exit status as well as its
|
||
output to =stdout=.
|
||
|
||
#+caption[Process utilities]:
|
||
#+caption: Process utilities.
|
||
#+name: lst:process-utilities
|
||
#+begin_src emacs-lisp
|
||
;; https://gitlab.com/howardabrams/spacemacs.d/blob/master/layers/ha-org/funcs.el#L418
|
||
(defun shell-command-with-exit-code (program &rest args)
|
||
"Run PROGRAM with ARGS and return exit-code and output in a list."
|
||
(with-temp-buffer
|
||
(list (apply 'call-process program nil (current-buffer) nil args)
|
||
(buffer-string))))
|
||
#+end_src
|
||
|
||
* [[info:emacs#Help][Help (info)]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:help
|
||
:END:
|
||
|
||
Table [[tab:help-key-bindings]] lists a number of key bindings to start playing with
|
||
the help facilities of Emacs.
|
||
|
||
#+attr_latex: :booktabs yes :float table
|
||
#+caption[Help key bindings]:
|
||
#+caption: Help key bindings.
|
||
#+name: tab:help-key-bindings
|
||
|--------------------------------+------------------+------------|
|
||
| command | keys | key map |
|
||
|--------------------------------+------------------+------------|
|
||
| =Info-goto-emacs-command-node= | {{{kbd(C-h F)}}} | =help-map= |
|
||
| =describe-function= | {{{kbd(C-h f)}}} | =help-map= |
|
||
| =describe-key= | {{{kbd(C-h k)}}} | =help-map= |
|
||
| =describe-symbol= | {{{kbd(C-h o)}}} | =help-map= |
|
||
| =describe-variable= | {{{kbd(C-h v)}}} | =help-map= |
|
||
| =info= | {{{kbd(C-h i)}}} | =help-map= |
|
||
|--------------------------------+------------------+------------|
|
||
|
||
** [[info:emacs#Name Help][Shortdoc-display-group (info)]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:shortdoc-display-group
|
||
:END:
|
||
|
||
Listing [[lst:configure-shortdoc]] binds {{{kbd(C-h y)}}} to
|
||
=short-doc-display-group= and defines a short documentation group for functions
|
||
defined in this Org file.
|
||
|
||
#+caption[Configure =shortdoc=]:
|
||
#+caption: Configure =shortdoc=.
|
||
#+name: lst:configure-shortdoc
|
||
#+begin_src emacs-lisp
|
||
(when (fboundp 'shortdoc-display-group)
|
||
(define-key help-map (kbd "y") #'shortdoc-display-group)
|
||
(with-eval-after-load 'shortdoc
|
||
;; Ensure defining the functions before documenting them.
|
||
(define-short-documentation-group init
|
||
"Advice"
|
||
(toggle-advice :no-manual t)
|
||
"Face"
|
||
(invert-default-face :no-manual t)
|
||
(set-default-face-height :no-manual t)
|
||
"LaTeX"
|
||
(TeX-brace-count-line-override :no-manual t)
|
||
(biber-delete-cache :no-manual t)
|
||
(toggle-TeX-brace-count-line-override :no-manual t)
|
||
(update-lualatex-opentype-font-name-database :no-manual t)
|
||
"Org"
|
||
(by-backend :no-manual t)
|
||
(by-backend-kbd-org-macro :no-manual t)
|
||
(org-babel-execute:latex-extra-header :no-manual t)
|
||
(org-babel-execute:latex-header :no-manual t)
|
||
(org-electric-dollar :no-manual t)
|
||
(org-eval-emacs-lisp-setup-blocks :no-manual t)
|
||
(org-eval-python-setup-blocks :no-manual t)
|
||
(org-eval-infixed-blocks :no-manual t)
|
||
(org-syntax-convert-keyword-case-to-lower :no-manual t)
|
||
"Wizard"
|
||
(enable-this-command :no-manual t)
|
||
(narrow-or-widen-dwim :no-manual t)
|
||
(org-narrow-to-table :no-manual t))))
|
||
#+end_src
|
||
|
||
** [[info:info#Top][Info (info)]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:info
|
||
:END:
|
||
|
||
Listing [[lst:configure-info]] adds a path in my home directory to the places where
|
||
=info= looks for files.
|
||
|
||
#+caption[Configure =info=]:
|
||
#+caption: Configure =info=.
|
||
#+name: lst:configure-info
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'info
|
||
;; Emacs should find my "python.info" file.
|
||
(add-to-list 'Info-directory-list
|
||
(expand-file-name "~/.local/share/info")))
|
||
#+end_src
|
||
|
||
* [[info:emacs#Key Bindings][Key bindings (info)]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:key-bindings
|
||
:END:
|
||
|
||
#+attr_latex: :booktabs yes :float table
|
||
#+caption[Basic key bindings]:
|
||
#+caption: Basic key bindings.
|
||
#+name: tab:basic-key-bindings
|
||
|----------------------+------------------------+--------------|
|
||
| command | keys | key map |
|
||
|----------------------+------------------------+--------------|
|
||
| =undo= | {{{kbd(s-z)}}} | =global-map= |
|
||
| =backward-kill-word= | {{{kbd(C-backspace)}}} | =global-map= |
|
||
| =backward-char= | {{{kbd(C-b)}}} | =global-map= |
|
||
| =forward-char= | {{{kbd(C-f)}}} | =global-map= |
|
||
| =backward-word= | {{{kbd(M-b)}}} | =global-map= |
|
||
| =forward-word= | {{{kbd(M-f)}}} | =global-map= |
|
||
| =backward-sentence= | {{{kbd(M-a)}}} | =global-map= |
|
||
| =forward-sentence= | {{{kbd(M-e)}}} | =global-map= |
|
||
|----------------------+------------------------+--------------|
|
||
|
||
** [[info:emacs#Disabling][Disabling Commands (info)]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:enable-disabled-commands
|
||
:END:
|
||
|
||
Execute src_emacs-lisp{(find-library "novice")} to see how Emacs prevents new
|
||
users from shooting themselves in the feet. Listing
|
||
[[lst:configure-disabled-command-function]] enables [[https://www.emacswiki.org/emacs/DisabledCommands][disabled commands on the fly]].
|
||
|
||
#+caption[Configure the =disabled-command-function=]:
|
||
#+caption: Configure the =disabled-command-function=.
|
||
#+name: lst:configure-disabled-command-function
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'emacs
|
||
(setq disabled-command-function
|
||
(defun enable-this-command (&rest _args)
|
||
"Called when a disabled command is executed.
|
||
Enable it and re-execute it."
|
||
(put this-command 'disabled nil)
|
||
(message "You typed %s. %s was disabled until now."
|
||
(key-description (this-command-keys)) this-command)
|
||
(sit-for 0)
|
||
(call-interactively this-command))))
|
||
#+end_src
|
||
|
||
** [[https://github.com/michael-heerdegen/interaction-log.el#readme][Interaction-log]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:interaction-log
|
||
:END:
|
||
|
||
#+caption[Configure =interaction-log=]:
|
||
#+caption: Configure =interaction-log=.
|
||
#+name: lst:configure-interaction-log
|
||
#+begin_src emacs-lisp
|
||
(when (and (ensure-package-installation 'interaction-log)
|
||
(require 'interaction-log nil 'noerror))
|
||
|
||
;; https://www.skybert.net/emacs/show-shortcuts-when-giving-presentations/
|
||
(defun ilog-ensure-ilog-buffer-window ()
|
||
"Ensure the visibility of the `ilog' buffer, when it exists."
|
||
(when (and (get-buffer ilog-buffer-name)
|
||
(not (get-buffer-window ilog-buffer-name)))
|
||
(display-buffer (get-buffer ilog-buffer-name))))
|
||
|
||
(defun toggle-ilog-timer-function-after ()
|
||
"Toggle `ilog-timer-function' advice."
|
||
(interactive)
|
||
(toggle-advice 'ilog-timer-function :after #'ilog-ensure-ilog-buffer-window))
|
||
|
||
(toggle-ilog-timer-function-after)
|
||
|
||
(define-key help-map (kbd "C-l") #'interaction-log-mode))
|
||
#+end_src
|
||
|
||
|
||
** [[https://github.com/tarsius/keycast#readme][Keycast]] :noexport:
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:keycast
|
||
:header-args:emacs-lisp: :tangle no
|
||
:END:
|
||
|
||
Listing [[lst:configure-keycast]] configures =keycast=.
|
||
|
||
#+caption[Configure =keycast=]:
|
||
#+caption: Configure =keycast=.
|
||
#+name: lst:configure-keycast
|
||
#+begin_src emacs-lisp
|
||
;; Make `keycast-log-update-buffer' use a buffer similar to the
|
||
;; control buffer `ediff-setup-windows-plain' returns.
|
||
(when (and (ensure-package-installation 'keycast)
|
||
(require 'keycast nil 'noerror))
|
||
(custom-set-variables
|
||
'(keycast-mode-line-window-predicate 'keycast-bottom-right-window-p))
|
||
|
||
(defun keycast-log-update-buffer-plain ()
|
||
(let ((buffer (get-buffer keycast-log-buffer-name)))
|
||
(unless (buffer-live-p buffer)
|
||
(setq buffer (get-buffer-create keycast-log-buffer-name))
|
||
(with-current-buffer buffer
|
||
(setq buffer-read-only t)))
|
||
(unless (get-buffer-window buffer)
|
||
(display-buffer buffer '(display-buffer-at-bottom
|
||
(dedicated . t)
|
||
(window-height . 10))))
|
||
(when-let ((output (keycast--format keycast-log-format)))
|
||
(with-current-buffer buffer
|
||
(goto-char (if keycast-log-newest-first (point-min) (point-max)))
|
||
(let ((inhibit-read-only t))
|
||
(when (and (> keycast--command-repetitions 0)
|
||
(string-match-p "%[rR]" keycast-log-format))
|
||
(unless keycast-log-newest-first
|
||
(backward-char))
|
||
(ignore-errors
|
||
(delete-region (line-beginning-position)
|
||
(1+ (line-end-position)))))
|
||
(insert output))
|
||
(goto-char (if keycast-log-newest-first (point-min) (point-max)))))))
|
||
|
||
(defun toggle-keycast-log-update-buffer-override ()
|
||
"Toggle `keycast-log-update-buffer' advice."
|
||
(interactive)
|
||
(toggle-advice 'keycast-log-update-buffer
|
||
:override #'keycast-log-update-buffer-plain))
|
||
|
||
(toggle-keycast-log-update-buffer-override))
|
||
#+end_src
|
||
|
||
* [[info:emacs#Emacs Server][Using Emacs as a server (info)]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:using-emacs-server
|
||
:END:
|
||
|
||
Emacs can act as a server that listens to a socket to share its state (for
|
||
instance buffers and command history) with other programs by means of a shell
|
||
command =emacsclient=. Section [[#sec:latexmk-save-compile-display-loop]] and
|
||
[[#sec:qutebrowser-userscript]] show how to use ~emacsclient~ to:
|
||
1. Install an asynchronous (or background) loop of saving a LaTeX file,
|
||
compiling it, and redisplaying the output in Emacs.
|
||
2. Make [[https://qutebrowser.org][qutebrowser]] send html links with document titles to Emacs.
|
||
The code in listing [[lst:start-emacs-server]] starts the Emacs server.
|
||
|
||
#+caption[Start the Emacs server]:
|
||
#+caption: Start the Emacs server.
|
||
#+name: lst:start-emacs-server
|
||
#+begin_src emacs-lisp
|
||
(when window-system
|
||
(unless (or noninteractive (daemonp))
|
||
(add-hook 'after-init-hook #'server-start)))
|
||
#+end_src
|
||
|
||
** Latexmk save-compile-display loop
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:latexmk-save-compile-display-loop
|
||
:END:
|
||
|
||
The =latexmk= resource file in the next source code block shows how to use
|
||
=emacsclient= to (re)display the PDF file in Emacs after each succesful
|
||
(re)compilation on condition that the settings of the ~compile-command~ local
|
||
variable in section are compatible. The local variable ~compile-command~ in the
|
||
[[#sec:local-variables][local variables]] section (only visible in =org= files, but not in =html= and
|
||
=pdf= files) shows how to use the =latexmkrc= file.
|
||
|
||
#+attr_latex: :options breaklines
|
||
#+caption[Tangle the Latexmk resource file]:
|
||
#+caption: Tangle the Latexmk resource file.
|
||
#+name: lst:latexmkrc
|
||
#+begin_src perl :tangle latexmkrc :comments none
|
||
# pdf creator
|
||
$pdf_mode = 4; # 4 means lualatex
|
||
# pdf previewer and update pdf previewer
|
||
$pdf_previewer = "emacsclient -e '(find-file-other-window %S)'";
|
||
$pdf_update_method = 4; # 4 runs a command to force the update
|
||
$pdf_update_command = "emacsclient -e '(with-current-buffer (find-buffer-visiting %S) (pdf-view-revert-buffer nil t))'";
|
||
# see for instance glossary.latexmkrc
|
||
add_cus_dep( 'acn', 'acr', 0, 'makeglossaries' );
|
||
add_cus_dep( 'glo', 'gls', 0, 'makeglossaries' );
|
||
$clean_ext .= " acr acn alg bbl dvi glo gls glg ist lol nav run.xml snm synctex.gz";
|
||
sub makeglossaries {
|
||
my ($name, $path) = fileparse( $$Psource );
|
||
return system "makeglossaries -d '$path' '$name'";
|
||
}
|
||
# Emacs looks for "Local variables:" after the last "newline-formfeed".
|
||
|
||
# Local Variables:
|
||
# mode: perl
|
||
# End:
|
||
#+end_src
|
||
|
||
** [[https://qutebrowser.org/doc/userscripts.html][Qutebrowser userscript]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:qutebrowser-userscript
|
||
:END:
|
||
|
||
The next block contains an userscript that sends a [[info:org#The store-link protocol][store-link org-protocol]]
|
||
message with the url and the title from [[https://qutebrowser.org][qutebrowser]] to =emacsclient=. The
|
||
function =urlencode= translates the url and the title for the message. The
|
||
[[info:python#Examples<22>][Python urllib examples]] show how to use =urlencode=. The final =execvp= call
|
||
deals with a [[https://qutebrowser.org][qutebrowser]] userscript requirement: the =emacsclient= process must
|
||
get the PID of the userscript that must kill itself after the take-over.
|
||
Termination of the =emacsclient= process hands control back to [[https://qutebrowser.org][qutebrowser]].
|
||
|
||
On a [[https://en.wikipedia.org/wiki/POSIX][POSIX]] system, you can run the userscript from [[https://qutebrowser.org][qutebrowser]] or from a
|
||
terminal to see whether it works. In case you try to run it from Emacs, Emacs
|
||
may hang or die.
|
||
|
||
#+caption[Tangle a qutebrowser userscript]:
|
||
#+caption: Tangle a qutebrowser userscript.
|
||
#+header: :comments none
|
||
#+header: :tangle-mode (identity #o755)
|
||
#+name: lst:qutebrowser-userscript
|
||
#+begin_src python :noeval :tangle org-store-link
|
||
#!/usr/bin/env python
|
||
from urllib.parse import urlencode
|
||
from os import environ, execvp
|
||
|
||
url = environ.get("QUTE_URL", "https://orgmode.org")
|
||
title = environ.get("QUTE_TITLE", "Org Mode")
|
||
parameters = urlencode({"url": url, "title": title})
|
||
print(payload := f"org-protocol://store-link?{parameters}")
|
||
execvp("emacsclient", ("-n", payload))
|
||
#+end_src
|
||
|
||
** TODO Look into: org-protocol handling with other browser on Darwin
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:org-protocol-darwin
|
||
:END:
|
||
|
||
1. [[http://rwx.io/posts/osx-uri-protocol-handler/][Patrick Goddi: macOS URI protocol handler]] and his [[https://github.com/fooqri/uri-handler][URI-Handler]].
|
||
2. [[https://www.hammerspoon.org/][Hammerspoon]]
|
||
3. [[https://vritser.github.io/posts/capture-anywhere/][Emacs Capture Anywhere]]
|
||
|
||
#+caption[Ensure =applescript-mode= installation]:
|
||
#+caption: Ensure =applescript-mode= installation.
|
||
#+name: lst:ensure-applescript-mode-installation
|
||
#+begin_src emacs-lisp
|
||
(when (ensure-package-installation 'applescript-mode))
|
||
#+end_src
|
||
|
||
#+caption[Applescript code to register =org-protocol= on Darwin]:
|
||
#+caption: Applescript code to register =org-protocol= on Darwin.
|
||
#+name: lst:applescript-org-protocol
|
||
#+begin_src applescript :tangle no
|
||
on emacsclient(input)
|
||
do shell script "/usr/local/bin/emacsclient -n -c '" & input & "'"
|
||
tell application "Emacs" to activate
|
||
end emacsclient
|
||
|
||
on open location input
|
||
emacsclient(input)
|
||
end open location
|
||
|
||
on open inputs
|
||
repeat with raw_input in inputs
|
||
set input to POSIX path of raw_input
|
||
emacsclient(input)
|
||
end repeat
|
||
end open
|
||
|
||
on run
|
||
do shell script emacsclient("")
|
||
end run
|
||
#+end_src
|
||
|
||
* Completion
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:completion
|
||
:END:
|
||
|
||
[[info:vertico#Top][Vertico (info)]] provides a performant and minimalistic vertical completion UI
|
||
based on the default completion system and behaves therefore correctly under all
|
||
circumstances. [[https://cestlaz.github.io/post/using-emacs-80-vertico/][Using Vertico, Marginalia, Consult, and Embark]] links to a video
|
||
demonstration. Vertico integrates well with fully supported complementary
|
||
packages to enrich the completion UI:
|
||
1. [[info:orderless#Top][Orderless (info)]] for an advanced completion style,
|
||
2. [[info:embark#Top][Embark (info)]] for minibuffer actions with context menus,
|
||
3. [[info:marginalia#Top][Marginalia (info)]] for rich annotations in the minibuffer, and
|
||
4. [[info:consult#Top][Consult (info)]] for useful search and navigation commands,
|
||
where the order is that of [[https://github.com/bdarcus/citar#installation][enhancing citar's experience]] and the configuration
|
||
steps below.
|
||
|
||
Finally, [[https://company-mode.github.io/][company: a modular complete-anything framework for Emacs]] provides
|
||
completion in any buffer and [[#sec:minibuffer-history-completion][minibuffer-history-completion]] provides completion
|
||
on previous input in the minibuffer.
|
||
|
||
** [[info:vertico#Top][Vertico (info)]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:vertico-configuration
|
||
:END:
|
||
|
||
Listing [[lst:enable-vertico-mode]] configures and enables =savehist-mode= and
|
||
enables =vertico-mode=. The documentation src_emacs-lisp{(describe-function
|
||
'savehist-mode)} why it is best to turn on =savehist-mode= in the Emacs init
|
||
file.
|
||
|
||
#+caption[Enable =savehist-mode= and =vertico-mode=]:
|
||
#+caption: Enable =savehist-mode= and =vertico-mode=.
|
||
#+name: lst:enable-vertico-mode
|
||
#+begin_src emacs-lisp
|
||
(when (fboundp 'savehist-mode)
|
||
(savehist-mode +1)
|
||
(custom-set-variables
|
||
'(savehist-additional-variables
|
||
'(eww-history
|
||
kill-ring
|
||
regexp-search-string
|
||
search-ring
|
||
search-string))))
|
||
(when (fboundp 'vertico-mode)
|
||
(vertico-mode +1))
|
||
(with-eval-after-load 'vertico
|
||
(define-key vertico-map (kbd "RET") #'vertico-directory-enter)
|
||
(define-key vertico-map (kbd "DEL") #'vertico-directory-delete-char)
|
||
(define-key vertico-map (kbd "M-DEL") #'vertico-directory-delete-word))
|
||
#+end_src
|
||
|
||
#+attr_latex: :booktabs yes :float table
|
||
#+caption[Vertico key map bindings]:
|
||
#+caption: Vertico key map bindings.
|
||
#+name: tab:vertico-keymap-bindings
|
||
|---------------------------------+---------------------+------------------------------------|
|
||
| command | keys | remap |
|
||
|---------------------------------+---------------------+------------------------------------|
|
||
| =vertico-directory-delete-char= | {{{kbd(DEL)}}} | |
|
||
| =vertico-directory-delete-word= | {{{kbd(M-DEL)}}} | |
|
||
| =vertico-directory-enter= | {{{kbd(RET)}}} | |
|
||
| =vertico-exit= | {{{kbd(C-j)}}} | =exit-minibuffer= |
|
||
| =vertico-exit-input= | {{{kbd(C-RET)}}} | |
|
||
| =vertico-first= | {{{kbd(M-<)}}} | =beginning-of-buffer= |
|
||
| =vertico-first= | {{{kbd(M-<)}}} | =minibuffer-beginning-of-buffer= |
|
||
| =vertico-insert= | {{{kbd(TAB)}}} | |
|
||
| =vertico-last= | {{{kbd(M->)}}} | =end-of-buffer= |
|
||
| =vertico-next-group= | {{{kbd(C-<down>)}}} | =forward-paragraph= |
|
||
| =vertico-next= | {{{kbd(<down>)}}} | =next-line-or-history-element= |
|
||
| =vertico-next= | {{{kbd(C-n)}}} | =next-line= |
|
||
| =vertico-previous-group= | {{{kbd(C-<up>)}}} | =backward-paragraph= |
|
||
| =vertico-previous= | {{{kbd(<up>)}}} | =previous-line-or-history-element= |
|
||
| =vertico-previous= | {{{kbd(C-p)}}} | =previous-line= |
|
||
| =vertico-save= | {{{kbd(M-w)}}} | =kill-ring-save= |
|
||
| =vertico-scroll-down= | {{{kbd(M-v)}}} | =scroll-down-command= |
|
||
| =vertico-scroll-up= | {{{kbd(C-v)}}} | =scroll-up-command= |
|
||
|---------------------------------+---------------------+------------------------------------|
|
||
|
||
** [[info:orderless#Top][Orderless (info)]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:orderless-configuration
|
||
:END:
|
||
|
||
Listing [[lst:configure-orderless]] configures [[info:orderless#Company][orderless for company (info)]].
|
||
|
||
#+caption[Configure =orderless=]:
|
||
#+caption: Configure =orderless=.
|
||
#+name: lst:configure-orderless
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'orderless
|
||
(custom-set-variables
|
||
'(orderless-component-separator " +"))
|
||
|
||
(defun just-one-face (fn &rest args)
|
||
(let ((orderless-match-faces [completions-common-part]))
|
||
(apply fn args)))
|
||
|
||
(advice-add 'company-capf--candidates :around #'just-one-face))
|
||
#+end_src
|
||
|
||
** [[info:embark#Top][Embark (info)]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:embark-configuration
|
||
:END:
|
||
|
||
Listing [[lst:configure-embark]] configures =embark= key bindings:
|
||
1. =embark-act= prompts the user for an action and performs it.
|
||
2. Except for highlighting of email and web URLs, =embark-dwim= englobes the
|
||
functionality of src_emacs-lisp{(find-library "goto-addr")} that activates
|
||
mail and web URLs to turn them into clickable buttons. Since =embark-dwim=
|
||
acts on a superset of target types, it renders =goto-addr= superfluous. See:
|
||
1. [[info:emacs#Goto Address mode][Goto Address mode (info)]].
|
||
2. [[info:embark#The default action on a target][The default (embark-dwim) action on a target (info)]].
|
||
3. =embark-bindings= allows to explore all current command key bindings in the
|
||
minibuffer.
|
||
4. The initialization src_emacs-lisp{(setq prefix-help-command
|
||
#'embark-prefix-help-command)} enables minibuffer help after a prefix key
|
||
(for instance {{{kbd(C-x)}}} or {{{kbd(C-c)}}}) as typing {{{kbd(C-x C-h)}}}
|
||
or {{{kbd(C-c C-h)}}} shows.
|
||
|
||
#+caption[Configure =embark=]:
|
||
#+caption: Configure =embark=.
|
||
#+name: lst:configure-embark
|
||
#+begin_src emacs-lisp
|
||
(when (cl-every #'fboundp '(embark-act embark-bindings embark-dwim))
|
||
(global-set-key (kbd "C-,") #'embark-act)
|
||
(global-set-key (kbd "C-:") #'embark-dwim)
|
||
(global-set-key (kbd "C-h B") #'embark-bindings)
|
||
(setq prefix-help-command #'embark-prefix-help-command))
|
||
#+end_src
|
||
|
||
** [[info:marginalia#Top][Marginalia (info)]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:marginalia-configuration
|
||
:END:
|
||
|
||
Listing [[lst:enable-marginalia-mode]] enables =marginalia-mode=.
|
||
|
||
#+caption[Enable =marginalia-mode=]:
|
||
#+caption: Enable =marginalia-mode=.
|
||
#+name: lst:enable-marginalia-mode
|
||
#+begin_src emacs-lisp
|
||
(when (fboundp 'marginalia-mode)
|
||
(marginalia-mode +1))
|
||
#+end_src
|
||
|
||
** [[info:consult#Top][Consult (info)]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:consult-configuration
|
||
:END:
|
||
|
||
Listing [[lst:configure-consult]] configures =consult=.
|
||
|
||
#+attr_latex: :booktabs yes :float table
|
||
#+caption[Configuration specific key bindings]:
|
||
#+caption: Configuration specific key-bindings.
|
||
#+name: tab:configuration-specific-key-bindings
|
||
|-------------------------------+---------------------+------------------------|
|
||
| command | keys | key map |
|
||
|-------------------------------+---------------------+------------------------|
|
||
| =consult-apropos= | {{{kbd(<help> a)}}} | =help-map= |
|
||
| =consult-bookmark= | {{{kbd(C-x r b)}}} | =ctl-x-r-keymap= |
|
||
| =consult-buffer-other-frame= | {{{kbd(C-x 5 b)}}} | =ctl-x-5-keymap= |
|
||
| =consult-buffer-other-window= | {{{kbd(C-x 4 b)}}} | =ctl-x-4-keymap= |
|
||
| =consult-buffer= | {{{kbd(C-x b)}}} | =ctl-x-keymap= |
|
||
| =consult-compile-error= | {{{kbd(M-g e)}}} | =goto-map= |
|
||
| =consult-complex-command= | {{{kbd(C-x M-:)}}} | =ctl-x-keymap= |
|
||
| =consult-find= | {{{kbd(M-s f)}}} | =search-map= |
|
||
| =consult-focus-lines= | {{{kbd(M-s u)}}} | =search-map= |
|
||
| =consult-git-grep= | {{{kbd(M-s g)}}} | =search-map= |
|
||
| =consult-global-mark= | {{{kbd(M-g k)}}} | =goto-map= |
|
||
| =consult-goto-line= | {{{kbd(M-g M-g)}}} | =goto-map= |
|
||
| =consult-goto-line= | {{{kbd(M-g g)}}} | =goto-map= |
|
||
| =consult-history= | {{{kbd(C-c h)}}} | =global-map= |
|
||
| =consult-imenu-project= | {{{kbd(M-g i)}}} | =goto-map= |
|
||
| =consult-keep-lines= | {{{kbd(M-s k)}}} | =search-map= |
|
||
| =consult-line= | {{{kbd(M-s l)}}} | =search-map= |
|
||
| =consult-mark= | {{{kbd(M-g m)}}} | =goto-map= |
|
||
| =consult-mode-command= | {{{kbd(C-c m)}}} | =global-map= |
|
||
| =consult-multi-occur= | {{{kbd(M-s m)}}} | =search-map= |
|
||
| =consult-outline= | {{{kbd(M-g o)}}} | =goto-map= |
|
||
| =consult-register= | {{{kbd(C-x r x)}}} | =ctl-x-r-keymap= |
|
||
| =consult-yank-pop= | {{{kbd(M-y)}}} | =global-map= |
|
||
|-------------------------------+---------------------+------------------------|
|
||
| =deadgrep= | {{{kbd(M-s d)}}} | =search-map= |
|
||
| =elfeed= | {{{kbd(C-x w)}}} | =global-map= |
|
||
| =embark-act= | {{{kbd(C-\,)}}} | =global-map= |
|
||
| =embark-bindings= | {{{kbd(C-h B)}}} | =global-map= |
|
||
| =embark-dwim= | {{{kbd(C-:)}}} | =global-map= |
|
||
| =iedit-mode= | {{{kbd(C-;)}}} | =global-map= |
|
||
| =minibuffer-complete-history= | {{{kbd(C-<tab>)}}} | =minibuffer-local-map= |
|
||
| =narrow-or-widen-dwim= | {{{kbd(C-x C-n)}}} | =ctl-x-keymap= |
|
||
| =org-agenda= | {{{kbd(C-c a)}}} | =global-map= |
|
||
| =org-capture= | {{{kbd(C-c c)}}} | =global-map= |
|
||
| =org-cite= | {{{kbd(C-c b)}}} | =org-mode-map= |
|
||
| =org-insert-link-global= | {{{kbd(C-c C-l)}}} | =global-map= |
|
||
| =org-narrow-to-table= | {{{kbd(C-x n t)}}} | =ctl-x-keymap= |
|
||
| =org-store-link= | {{{kbd(C-c l)}}} | =global-map= |
|
||
|-------------------------------+---------------------+------------------------|
|
||
|
||
|
||
#+caption[Configure =consult=]:
|
||
#+caption: Configure =consult=.
|
||
#+name: lst:configure-consult
|
||
#+begin_src emacs-lisp
|
||
(when (fboundp 'consult-apropos)
|
||
(custom-set-variables
|
||
'(consult-project-root-function #'vc-root-dir))
|
||
;; C-c bindings (current-global-map)
|
||
(global-set-key (kbd "C-c h") #'consult-history)
|
||
(global-set-key (kbd "C-c m") #'consult-mode-command)
|
||
;; C-h bindings (help-map)
|
||
(define-key help-map (kbd "a") #'consult-apropos)
|
||
;; C-x bindings (ctl-x-map)
|
||
(define-key ctl-x-map (kbd "M-:") #'consult-complex-command)
|
||
(define-key ctl-x-map (kbd "b") #'consult-buffer)
|
||
(define-key ctl-x-4-map (kbd "b") #'consult-buffer-other-window)
|
||
(define-key ctl-x-5-map (kbd "b") #'consult-buffer-other-frame)
|
||
(define-key ctl-x-r-map (kbd "x") #'consult-register)
|
||
(define-key ctl-x-r-map (kbd "b") #'consult-bookmark)
|
||
;; M-g bindings (goto-map)
|
||
(define-key goto-map (kbd "g") #'consult-goto-line)
|
||
(define-key goto-map (kbd "M-g") #'consult-goto-line)
|
||
(define-key goto-map (kbd "o") #'consult-outline)
|
||
(define-key goto-map (kbd "m") #'consult-mark)
|
||
(define-key goto-map (kbd "k") #'consult-global-mark)
|
||
(define-key goto-map (kbd "i") #'consult-imenu-project)
|
||
(define-key goto-map (kbd "e") #'consult-compile-error)
|
||
;; M-s bindings (search-map)
|
||
(define-key search-map (kbd "g") #'consult-git-grep)
|
||
(define-key search-map (kbd "f") #'consult-find)
|
||
(define-key search-map (kbd "k") #'consult-keep-lines)
|
||
(define-key search-map (kbd "l") #'consult-line)
|
||
(define-key search-map (kbd "m") #'consult-multi-occur)
|
||
(define-key search-map (kbd "u") #'consult-focus-lines)
|
||
;; Other bindings (current-global-map)
|
||
(global-set-key (kbd "M-y") #'consult-yank-pop)
|
||
;; Tweak functions
|
||
(advice-add 'completing-read-multiple
|
||
:override #'consult-completing-read-multiple))
|
||
#+end_src
|
||
|
||
** [[https://company-mode.github.io/][Company: a modular complete anything framework for Emacs]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:company-configuration
|
||
:END:
|
||
|
||
Listing [[lst:configure-company]] configures =company=.
|
||
|
||
#+caption[Configure =company=]:
|
||
#+caption: Configure =company=.
|
||
#+name: lst:configure-company
|
||
#+begin_src emacs-lisp
|
||
(when (fboundp 'company-mode)
|
||
(custom-set-variables
|
||
;; https://github.com/purcell/emacs.d/issues/778
|
||
'(company-transformers '(company-sort-by-occurrence)))
|
||
(dolist (hook '(LaTeX-mode-hook
|
||
org-mode-hook
|
||
emacs-lisp-mode-hook
|
||
lisp-interaction-mode-hook
|
||
lisp-mode-hook
|
||
python-mode-hook
|
||
ielm-mode-hook
|
||
sly-mrepl-mode-hook))
|
||
(add-hook hook #'company-mode)))
|
||
#+end_src
|
||
|
||
** [[https://lists.gnu.org/archive/html/emacs-devel/2021-12/msg00802.html][Minibuffer history completion]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:minibuffer-history-completion
|
||
:END:
|
||
|
||
See [[https://lists.gnu.org/archive/html/emacs-devel/2021-12/msg00802.html][Juri Linkov (Emacs Developer mailing list)]] for how to allow completion on
|
||
previous input in the minibuffer. Listing
|
||
[[lst:enable-minibuffer-history-completion]] enables minibuffer history completion.
|
||
|
||
#+caption[Enable =minibuffer-history-completion=]:
|
||
#+caption: Enable =minibuffer-history-completion=.
|
||
#+name: lst:enable-minibuffer-history-completion
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'minibuffer
|
||
;; https://github.com/oantolin/emacs-config/blob/master/init.el#L333
|
||
(custom-set-variables
|
||
'(completion-category-defaults nil)
|
||
'(completion-category-overrides '((file (styles basic partial-completion))))
|
||
'(completion-ignore-case t)
|
||
'(completion-styles '(orderless basic partial-completion)))
|
||
|
||
(defun minibuffer-setup-history-completions ()
|
||
(unless (or minibuffer-completion-table minibuffer-completion-predicate)
|
||
(setq-local minibuffer-completion-table
|
||
(symbol-value minibuffer-history-variable))))
|
||
|
||
(add-hook 'minibuffer-setup-hook 'minibuffer-setup-history-completions)
|
||
|
||
;; Stolen from Emacs-28.1 for Emacs-27.2:
|
||
(unless (fboundp 'minibuffer--completion-prompt-end)
|
||
(defun minibuffer--completion-prompt-end ()
|
||
(let ((end (minibuffer-prompt-end)))
|
||
(if (< (point) end)
|
||
(user-error "Can't complete in prompt")
|
||
end))))
|
||
|
||
;; Adapted from ‘minibuffer-complete’:
|
||
(defun minibuffer-complete-history ()
|
||
"Allow minibuffer completion on previous input."
|
||
(interactive)
|
||
(completion-in-region (minibuffer--completion-prompt-end) (point-max)
|
||
(symbol-value minibuffer-history-variable)
|
||
nil))
|
||
|
||
(define-key minibuffer-local-map (kbd "C-<tab>") #'minibuffer-complete-history))
|
||
#+end_src
|
||
|
||
* [[info:emacs#Search][Search and replace (info)]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:search-replace
|
||
:END:
|
||
|
||
** [[https://github.com/Wilfred/deadgrep#readme][Deadgrep]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:deadgrep
|
||
:END:
|
||
|
||
[[https://github.com/Wilfred/deadgrep#readme][Deadgrep]] uses [[https://github.com/BurntSushi/ripgrep#readme][ripgrep]] for superfast text searching in the default directory or
|
||
the current [[https://en.wikipedia.org/wiki/Version_control][VCS]] directory tree. Listing [[lst:configure-deadgrep]] binds =deadgrep=
|
||
to {{{kbd(M-s d)}}} and =deadgrep-edit-mode= to {{{kbd(C-c C-w)}}}.
|
||
|
||
#+caption[Configure =deadgrep=]:
|
||
#+caption: Configure =deadgrep=.
|
||
#+name: lst:configure-deadgrep
|
||
#+begin_src emacs-lisp
|
||
(when (and (ensure-package-installation 'deadgrep)
|
||
(fboundp 'deadgrep))
|
||
(define-key search-map (kbd "d") #'deadgrep)
|
||
(with-eval-after-load 'deadgrep
|
||
(define-key deadgrep-mode-map (kbd "C-c C-w") #'deadgrep-edit-mode)))
|
||
#+end_src
|
||
|
||
* [[info:emacs#Version Control][Version Control (info)]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:version-control
|
||
:END:
|
||
|
||
** [[info:ediff#Top][Ediff (info)]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:ediff
|
||
:END:
|
||
|
||
Video links to complete the [[info:ediff#Top][ediff (info)]] manual are:
|
||
1. [[https://www.youtube.com/watch?v=6ZWp05OW1c0][Emergency Emacs]].
|
||
2. [[https://protesilaos.com/codelog/2020-04-10-emacs-smerge-ediff/][Use =smerge= and =ediff= to resolve file conflicts]].
|
||
Listing [[lst:configure-ediff]] configures =ediff= to display all its buffers in a
|
||
single frame and to make all text visible prior to ediffing Org buffers.
|
||
|
||
#+caption[Configure =ediff=]:
|
||
#+caption: Configure =ediff=.
|
||
#+name: lst:configure-ediff
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'emacs
|
||
(custom-set-variables
|
||
'(ediff-merge-split-window-function #'split-window-horizontally)
|
||
'(ediff-split-window-function #'split-window-horizontally)
|
||
'(ediff-window-setup-function #'ediff-setup-windows-plain)))
|
||
(with-eval-after-load 'org
|
||
;; https://github.com/oantolin/emacs-config#readme
|
||
(defun ediff-with-org-show-all ()
|
||
"Expand all headings prior to ediffing org buffers."
|
||
(add-hook 'ediff-prepare-buffer-hook #'org-show-all nil t))
|
||
(add-hook 'org-mode-hook #'ediff-with-org-show-all))
|
||
#+end_src
|
||
|
||
* Reading
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:reading
|
||
:END:
|
||
|
||
** Reading [[https://en.wikipedia.org/wiki/DjVu][DjVu]] files
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:reading-djvu-files
|
||
:END:
|
||
|
||
This setup relies on [[info:emacs#Document View][Document View (info)]] to facilitate reading [[https://en.wikipedia.org/wiki/DjVu][DjVu]] files.
|
||
Reading the code shown by src_emacs-lisp{(find-function
|
||
'doc-view-djvu->tiff-converter-ddjvu)} shows that reading [[https://en.wikipedia.org/wiki/DjVu][DjVu]] files requires
|
||
the command line [[https://en.wikipedia.org/wiki/DjVu][DjVu]] decoder =ddjvu= from the [[http://djvu.sourceforge.net/][DjVuLibre]] utilities.
|
||
|
||
** Reading EPUB files
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:reading-epub-files
|
||
:END:
|
||
|
||
The package [[https://depp.brause.cc/nov.el/][nov.el]] provides a major mode for reading EPUB files in Emacs.
|
||
Listing [[lst:configure-nov]] configures [[https://depp.brause.cc/nov.el/][nov.el]].
|
||
|
||
#+caption[Configure =nov=]:
|
||
#+caption: Configure =nov=.
|
||
#+name: lst:configure-nov
|
||
#+begin_src emacs-lisp
|
||
(when (and (ensure-package-installation 'nov)
|
||
(fboundp 'nov-mode))
|
||
(add-to-list 'auto-mode-alist `(,(rx ".epub" eos) . nov-mode)))
|
||
#+end_src
|
||
|
||
** Reading PDF files
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:reading-pdf-files
|
||
:END:
|
||
|
||
The [[https://github.com/vedang/pdf-tools][pdf-tools]] package exploits the [[https://github.com/freedesktop/poppler][poppler]] library to render and to let you
|
||
annotate [[https://en.wikipedia.org/wiki/PDF][PDF]] files. It also exploits the [[https://wiki.contextgarden.net/SyncTeX][SyncTeX]] library to link anchors in [[https://en.wikipedia.org/wiki/PDF][PDF]]
|
||
files produced with LaTeX to the original LaTeX sources. The [[https://github.com/nicolaisingh/saveplace-pdf-view#readme][saveplace-pdf-view]]
|
||
package saves =pdf-view= and =doc-view= places.
|
||
|
||
In order to use [[https://github.com/vedang/pdf-tools][pdf-tools]], you have to type {{{kbd(M-x pdf-tools-install)}}} after
|
||
installation of [[https://github.com/vedang/pdf-tools][pdf-tools]] from [[https://melpa.org/][MELPA]] or after each update of [[https://github.com/freedesktop/poppler][poppler]] to build or
|
||
rebuild the =epdfinfo= executable that serves the [[https://en.wikipedia.org/wiki/PDF][PDF]] files to Emacs.
|
||
|
||
#+caption[Configure =pdf-tools=]:
|
||
#+caption: Configure =pdf-tools=.
|
||
#+name: lst:configure-pdf-tools
|
||
#+begin_src emacs-lisp
|
||
(when (and (ensure-package-installation 'pdf-tools 'saveplace-pdf-view)
|
||
(fboundp 'pdf-loader-install))
|
||
;; `pdf-loader-install' is the lazy equivalent of `pdf-tools-install':
|
||
;; see the README file.
|
||
(pdf-loader-install)
|
||
|
||
(with-eval-after-load 'pdf-outline
|
||
;; Unmask the `image-save' key binding in `pdf-view-mode-map' and
|
||
;; in `image-mode-map' (by parenthood).
|
||
(define-key pdf-outline-minor-mode-map (kbd "o") nil)
|
||
(define-key pdf-outline-minor-mode-map (kbd "O") #'pdf-outline))
|
||
|
||
(with-eval-after-load 'pdf-view
|
||
(custom-set-variables
|
||
'(pdf-view-display-size 'fit-page)
|
||
`(pdf-view-use-scaling ,(eq system-type 'darwin)))
|
||
(require 'saveplace-pdf-view nil 'noerror)))
|
||
#+end_src
|
||
|
||
* Writing
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:writing
|
||
:END:
|
||
|
||
** Writing LaTeX files
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:writing-latex-files
|
||
:END:
|
||
|
||
Loading =tex.el= immediately instead of lazily ensures proper initialization of
|
||
[[https://en.wikipedia.org/wiki/AUCTeX][AUCTeX]]. For instance, the ~TeX-master~ safe local variable in the =tex.el=
|
||
elisp library file has no autoload cookie. Without prior loading of =tex.el=,
|
||
Emacs will complain that ~TeX-master~ is no safe local variable in case it reads
|
||
a LaTeX file that sets ~TeX-master~. Listing [[lst:require-auctex]] initializes
|
||
[[https://en.wikipedia.org/wiki/AUCTeX][AUCTeX]] properly for LuaTeX or LuaLaTeX. In case the output of =LuaLaTeX= has
|
||
missing fonts, listing [[lst:update-lualatex-opentype-font-name-database]] defines a
|
||
function to update the =OpenType Font= name database for =LuaLaTeX=. Finally,
|
||
out of the box, [[https://en.wikipedia.org/wiki/AUCTeX][AUCTeX]] does not indent text between square brackets. The code
|
||
in listing [[lst:configure-auctex]] corrects this by advising to override
|
||
~TeX-brace-count-line~ with ~TeX-brace-count-line-advice~.
|
||
|
||
#+caption[Require =AUCTeX=]:
|
||
#+caption: Require =AUCTeX=.
|
||
#+name: lst:require-auctex
|
||
#+begin_src emacs-lisp
|
||
;; Use `require' to make `TeX-master' a safe local variable.
|
||
(when (require 'tex nil 'noerror)
|
||
(custom-set-variables
|
||
'(TeX-auto-save t)
|
||
'(TeX-engine 'luatex)
|
||
'(TeX-install-font-lock #'font-latex-setup)
|
||
'(TeX-parse-self t)
|
||
;; Disable `TeX-electric-math' to prevent collisions with `smartparens'.
|
||
'(TeX-electric-math nil)))
|
||
#+end_src
|
||
|
||
|
||
#+caption[Update the =LuaLaTeX OpenType Font= name database]:
|
||
#+caption: Update the =LuaLaTeX= =OpenType Font= name database.
|
||
#+name: lst:update-lualatex-opentype-font-name-database
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'emacs
|
||
(defun update-lualatex-opentype-font-name-database ()
|
||
"Update the \"OpenType Font\" name database for \"LuaLaTeX\"."
|
||
(interactive)
|
||
(cl-destructuring-bind (exit-code output)
|
||
(shell-command-with-exit-code
|
||
"luaotfload-tool" "-vv" "--update" "--force")
|
||
(if (= 0 exit-code) (message "%s" (string-trim output))
|
||
(error "%s" (string-trim output))))))
|
||
#+end_src
|
||
|
||
#+caption[Configure =AUCTeX=]:
|
||
#+caption: Configure =AUCTeX=.
|
||
#+name: lst:configure-auctex
|
||
#+begin_src emacs-lisp
|
||
(when (require 'tex nil 'noerror)
|
||
;; https://emacs.stackexchange.com/a/35507 answers:
|
||
;; How to indent between square brackets?
|
||
(defun TeX-brace-count-line-override ()
|
||
"Count number of open/closed braces."
|
||
(save-excursion
|
||
(let ((count 0) (limit (line-end-position)) char)
|
||
(while (progn
|
||
(skip-chars-forward "^{}[]\\\\" limit)
|
||
(when (and (< (point) limit) (not (TeX-in-comment)))
|
||
(setq char (char-after))
|
||
(forward-char)
|
||
(cond ((eq char ?\{)
|
||
(setq count (+ count TeX-brace-indent-level)))
|
||
((eq char ?\})
|
||
(setq count (- count TeX-brace-indent-level)))
|
||
((eq char ?\[)
|
||
(setq count (+ count TeX-brace-indent-level)))
|
||
((eq char ?\])
|
||
(setq count (- count TeX-brace-indent-level)))
|
||
((eq char ?\\)
|
||
(when (< (point) limit)
|
||
(forward-char) t))))))
|
||
count)))
|
||
|
||
(defun toggle-TeX-brace-count-line-override ()
|
||
"Toggle `TeX-brace-count-line-override' advice."
|
||
(interactive)
|
||
(toggle-advice 'TeX-brace-count-line :override #'TeX-brace-count-line-override))
|
||
|
||
(toggle-TeX-brace-count-line-override))
|
||
#+end_src
|
||
|
||
Listing [[lst:configure-bibtex]] configures the Emacs =bibtex= library to use the
|
||
LaTeX =BiBTeX= dialect for backwards compatibility. Listing
|
||
[[lst:configure-font-latex]] disables font scaling of section titles. Listing
|
||
[[lst:configure-latex]] configures =latex= for a full featured
|
||
=LaTeX-section-command=.
|
||
|
||
#+caption[Configure =bibtex=]:
|
||
#+caption: Configure =bibtex=.
|
||
#+name: lst:configure-bibtex
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'bibtex
|
||
(custom-set-variables '(bibtex-dialect 'BibTeX)))
|
||
#+end_src
|
||
|
||
#+caption[Configure =font-latex=]:
|
||
#+caption: Configure =font-latex=.
|
||
#+name: lst:configure-font-latex
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'font-latex
|
||
(custom-set-variables
|
||
'(font-latex-fontify-sectioning 1.0)))
|
||
#+end_src
|
||
|
||
#+caption[Configure =latex=]:
|
||
#+caption: Configure =latex=.
|
||
#+name: lst:configure-latex
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'latex
|
||
(custom-set-variables
|
||
'(LaTeX-electric-left-right-brace t)
|
||
'(LaTeX-section-hook '(LaTeX-section-heading
|
||
LaTeX-section-title
|
||
LaTeX-section-toc
|
||
LaTeX-section-section
|
||
LaTeX-section-label))))
|
||
#+end_src
|
||
|
||
*** [[https://gitlab.com/matsievskiysv/math-preview/-/blob/master/README.md][Math-preview]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:math-preview
|
||
:END:
|
||
|
||
[[https://gitlab.com/matsievskiysv/math-preview/-/blob/master/README.md][Math-preview]] uses [[https://docs.mathjax.org/en/latest/][Mathjax-3]] to display [[https://www.latex-project.org/][LaTeX]], [[https://www.w3.org/Math/][MathML]],and [[http://asciimath.org/][asciimath]] in Emacs
|
||
buffers with help of an external [[https://nodejs.org][node.js]] program.
|
||
|
||
#+caption[Configure =math-preview=]:
|
||
#+caption: Configure =math-preview=.
|
||
#+name: lst:configure-math-preview
|
||
#+begin_src emacs-lisp
|
||
(when (ensure-package-installation 'math-preview)
|
||
(with-eval-after-load 'math-preview
|
||
;; https://docs.mathjax.org/en/latest/input/tex/extensions/physics.html
|
||
(let ((physics (split-string "
|
||
abs absolutevalue acomm acos acosecant acosine acot acotangent
|
||
acsc admat anticommutator antidiagonalmatrix arccos arccosecant
|
||
arccosine arccot arccotangent arccsc arcsec arcsecant arcsin
|
||
arcsine arctan arctangent asec asecant asin asine atan atangent
|
||
bmqty bqty Bqty bra braket comm commutator cos cosecant cosh
|
||
cosine cot cotangent coth cp cross crossproduct csc csch curl dd
|
||
derivative det determinant diagonalmatrix diffd differential div
|
||
divergence dmat dotproduct dv dyad erf ev eval evaluated exp
|
||
expectationvalue exponential expval fderivative fdv flatfrac
|
||
functionalderivative grad gradient gradientnabla hypcosecant
|
||
hypcosine hypcotangent hypsecant hypsine hyptangent
|
||
identitymatrix Im imaginary imat innerproduct ip ket ketbra
|
||
laplacian ln log logarithm matrixdeterminant matrixel
|
||
matrixelement matrixquantity mdet mel mqty naturallogarithm norm
|
||
op order outerproduct partialderivative paulimatrix pb
|
||
pderivative pdv pmat pmqty Pmqty poissonbracket pqty Pr
|
||
principalvalue Probability pv PV qall qand qas qassume qc qcc
|
||
qcomma qelse qeven qfor qgiven qif qin qinteger qlet qodd qor
|
||
qotherwise qq qqtext qsince qthen qty quantity qunless qusing
|
||
rank Re real Res Residue sbmqty sec secant sech sin sine sinh
|
||
smallmatrixquantity smdet smqty spmqty sPmqty svmqty tan tangent
|
||
tanh tr Tr trace Trace va var variation vb vdot vectorarrow
|
||
vectorbold vectorunit vmqty vnabla vqty vu xmat xmatrix
|
||
zeromatrix zmat")))
|
||
(cl-pushnew `("physics" . ,physics)
|
||
math-preview-tex-packages-autoload-packages))
|
||
(setq math-preview-raise 0.5
|
||
math-preview-scale 1
|
||
math-preview-tex-default-packages '("autoload" "ams" "physics"))
|
||
(let ((command (executable-find "~/node_modules/.bin/math-preview")))
|
||
(if command
|
||
(setq math-preview-command command)
|
||
;; https://stackoverflow.com/a/17509764 answers:
|
||
;; How to install an npm package from github directly?
|
||
(unless (file-directory-p "~/node_modules")
|
||
(make-directory "~/node_modules"))
|
||
(cl-destructuring-bind (exit-code output)
|
||
(shell-command-with-exit-code
|
||
"npm" "install" "git+https://gitlab.com/matsievskiysv/math-preview.git")
|
||
(if (= 0 exit-code) (message "%s" (string-trim output))
|
||
(error "%s" (string-trim output))))))))
|
||
#+end_src
|
||
|
||
*** TODO Improve the AUCTeX configuration slowly
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:configure-auctex-slowly
|
||
:END:
|
||
|
||
[[https://github.com/thisirs/dotemacs/blob/master/lisp/init-auctex.el][AUCTeX setup of an experienced user]]
|
||
|
||
** Writing Org files
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:writing-org-files
|
||
:END:
|
||
|
||
*** [[info:org#Activation][Org activation (info)]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:activate-org
|
||
:END:
|
||
|
||
#+caption[Activate =Org=]:
|
||
#+caption: Activate =Org=.
|
||
#+name: lst:activate-org
|
||
#+begin_src emacs-lisp
|
||
(when (cl-every #'fboundp '(org-agenda org-capture))
|
||
(global-set-key (kbd "C-c a") #'org-agenda)
|
||
(global-set-key (kbd "C-c c") #'org-capture)
|
||
(with-eval-after-load 'ol
|
||
(global-set-key (kbd "C-c l") #'org-store-link)
|
||
(global-set-key (kbd "C-c C-l") #'org-insert-link-global)))
|
||
#+end_src
|
||
|
||
*** Org customization
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:customize-org
|
||
:END:
|
||
|
||
The code in listing [[lst:customize-org-babel]], [[lst:customize-org]],
|
||
[[lst:customize-org-link]], [[lst:customize-org-export]], and
|
||
[[lst:customize-org-latex-export]] does basic customization of [[https://orgmode.org/][Org-mode]] variables.
|
||
Listing [[lst:customize-org-link]] configures =org-link= to use relative file path
|
||
links. Listing [[lst:customize-org-latex-classes]] defines [[info:org#LaTeX specific export settings][org-latex-classes (info)]]
|
||
for backward compatibility. See table [[tab:org-latex-class-tag-placeholder]] and
|
||
type {{{kbd(C-h v org-latex-classes)}}} for an explanation of the code in
|
||
listing [[lst:customize-org-latex-classes]].
|
||
|
||
#+attr_latex: :booktabs yes :float table
|
||
#+caption[The relation tag-placeholder in listing [[lst:customize-org-latex-classes]]]:
|
||
#+caption: The relation tag-placeholder in listing [[lst:customize-org-latex-classes]].
|
||
#+name: tab:org-latex-class-tag-placeholder
|
||
| tag | placeholder |
|
||
|-----+-----------------------|
|
||
| +1 | [DEFAULT-PACKAGES] |
|
||
| +2 | [PACKAGES] |
|
||
| +3 | [EXTRA] |
|
||
| -1 | [NO-DEFAULT-PACKAGES] |
|
||
| -2 | [NO-PACKAGES] |
|
||
| -3 | [NO-EXTRA] |
|
||
|
||
#+caption[Customize =org-babel=]:
|
||
#+caption: Customize =org-babel=.
|
||
#+name: lst:customize-org-babel
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'ob-core
|
||
(custom-set-variables
|
||
'(org-confirm-babel-evaluate nil)))
|
||
|
||
(with-eval-after-load 'ob-latex
|
||
(custom-set-variables
|
||
'(org-babel-latex-preamble
|
||
(lambda (_)
|
||
"\\documentclass[preview]{standalone}\n"))
|
||
'(org-babel-latex-begin-env
|
||
(lambda (_)
|
||
"\\begin{document}\n"))
|
||
'(org-babel-latex-end-env
|
||
(lambda (_)
|
||
"\\end{document}\n"))))
|
||
|
||
(with-eval-after-load 'ob-lisp
|
||
(with-eval-after-load 'sly
|
||
(custom-set-variables
|
||
'(org-babel-lisp-eval-fn #'sly-eval))))
|
||
|
||
(with-eval-after-load 'ob-python
|
||
(custom-set-variables
|
||
'(org-babel-python-command "python -E")))
|
||
#+end_src
|
||
|
||
#+caption[Customize =Org=]:
|
||
#+caption: Customize =Org=.
|
||
#+name: lst:customize-org
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'org
|
||
(custom-set-variables
|
||
'(org-babel-load-languages '((C . t)
|
||
(calc . t)
|
||
(dot . t)
|
||
(emacs-lisp . t)
|
||
(eshell . t)
|
||
(fortran . t)
|
||
(gnuplot . t)
|
||
(latex . t)
|
||
(lisp . t)
|
||
(maxima . t)
|
||
(org . t)
|
||
(perl . t)
|
||
(python . t)
|
||
(shell . t)))
|
||
'(org-export-backends '(ascii beamer html icalendar latex odt texinfo))
|
||
'(org-file-apps '((auto-mode . emacs)
|
||
(directory . emacs)
|
||
("\\.mm\\'" . default)
|
||
("\\.x?html?\\'" . default)
|
||
("\\.pdf\\'" . emacs)))
|
||
'(org-modules '(ol-bibtex
|
||
ol-doi
|
||
ol-eww
|
||
ol-info
|
||
org-id
|
||
org-protocol
|
||
org-tempo))
|
||
'(org-structure-template-alist '(("a" . "export ascii")
|
||
("c" . "center")
|
||
("C" . "comment")
|
||
("e" . "example")
|
||
("E" . "export")
|
||
("h" . "export html")
|
||
("l" . "export latex")
|
||
("q" . "quote")
|
||
("s" . "src")
|
||
("p" . "src python :session :async")
|
||
("v" . "verse")))))
|
||
#+end_src
|
||
|
||
#+caption[Configure =org-mode-map=]:
|
||
#+caption: Configure =org-mode-map=.
|
||
#+name: lst:configure-org-mode-map
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'emacs
|
||
;; From: "Nicolas Richard" <theonewiththeevillook@yahoo.fr>
|
||
;; Date: Fri, 08 Mar 2013 16:23:02 +0100 [thread overview]
|
||
;; Message-ID: <87vc913oh5.fsf@yahoo.fr> (raw)
|
||
(defun org-electric-dollar ()
|
||
"When called once, insert \\(\\) and leave point in between.
|
||
When called twice, replace the previously inserted \\(\\) by one $."
|
||
(interactive)
|
||
(if (and (looking-at "\\\\)") (looking-back "\\\\(" (- (point) 2)))
|
||
(progn (delete-char 2)
|
||
(delete-char -2)
|
||
(insert "$"))
|
||
(insert "\\(\\)")
|
||
(backward-char 2)))
|
||
|
||
(with-eval-after-load 'org
|
||
(define-key org-mode-map (kbd "$") #'org-electric-dollar)
|
||
(define-key org-mode-map (kbd "M-q") #'org-fill-paragraph)
|
||
(when (require 'org-menu nil 'noerror)
|
||
(define-key org-mode-map (kbd "C-c m") 'org-menu))))
|
||
#+end_src
|
||
|
||
#+caption[Customize =org-link=]:
|
||
#+caption: Customize =org-link=.
|
||
#+name: lst:customize-org-link
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'ol
|
||
(custom-set-variables
|
||
'(org-link-file-path-type 'relative)))
|
||
#+end_src
|
||
|
||
#+caption[Customize =org-export=]:
|
||
#+caption: Customize =org-export=.
|
||
#+name: lst:customize-org-export
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'ox
|
||
(custom-set-variables
|
||
'(org-export-dispatch-use-expert-ui t)))
|
||
#+end_src
|
||
|
||
#+caption[Customize =org-latex-export=]:
|
||
#+caption: Customize =org-latex-export=.
|
||
#+name: lst:customize-org-latex-export
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'org
|
||
(custom-set-variables
|
||
'(org-latex-default-packages-alist '(("" "fontspec" t ("lualatex"))
|
||
("AUTO" "inputenc" t ("pdflatex"))
|
||
("T1" "fontenc" t ("pdflatex"))
|
||
("" "graphicx" t)
|
||
("" "longtable" nil)
|
||
("" "wrapfig" nil)
|
||
("" "rotating" nil)
|
||
("normalem" "ulem" t)
|
||
("" "amsmath" t)
|
||
("" "amssymb" t)
|
||
("" "capt-of" nil)
|
||
("" "hyperref" nil)))))
|
||
|
||
(with-eval-after-load 'ox-latex
|
||
(custom-set-variables
|
||
'(org-latex-compiler "lualatex")
|
||
'(org-latex-hyperref-template "\\hypersetup{
|
||
pdfauthor={%a},
|
||
pdftitle={%t},
|
||
pdfkeywords={%k},
|
||
pdfsubject={%d},
|
||
pdfcreator={%c},
|
||
pdflang={%L},
|
||
citecolor=blue,
|
||
colorlinks=true,
|
||
filecolor=blue,
|
||
hyperfootnotes=false,
|
||
linkcolor=blue,
|
||
unicode=true,
|
||
urlcolor=blue,
|
||
}\n")
|
||
'(org-latex-listings 'minted)
|
||
'(org-latex-minted-langs '((cc "c++")
|
||
(conf "text")
|
||
(cperl "perl")
|
||
(diff "diff")
|
||
(shell-script "bash")
|
||
(org "text")
|
||
(toml "toml")))
|
||
'(org-latex-minted-options '(("bgcolor" "LightGoldenrodYellow")))
|
||
`(org-latex-logfiles-extensions
|
||
',(cl-union '("lof" "lot") org-latex-logfiles-extensions :test #'equal))
|
||
'(org-latex-prefer-user-labels t)
|
||
'(org-latex-subtitle-separate t)))
|
||
#+end_src
|
||
|
||
#+caption[Customize =org-latex-classes= for backwards compatibility]:
|
||
#+caption: Customize =org-latex-classes= for backwards compatibility.
|
||
#+name: lst:customize-org-latex-classes
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'ox-latex
|
||
(mapc (function (lambda (element)
|
||
(add-to-list 'org-latex-classes element)))
|
||
(nreverse
|
||
(quote (("elsarticle-1+2+3" ; Elsevier journals
|
||
"\\documentclass{elsarticle}
|
||
[NO-DEFAULT-PACKAGES]
|
||
[PACKAGES]
|
||
[EXTRA]"
|
||
("\\section{%s}" . "\\section*{%s}")
|
||
("\\subsection{%s}" . "\\subsection*{%s}")
|
||
("\\subsubsection{%s}" . "\\subsubsection*{%s}")
|
||
("\\paragraph{%s}" . "\\paragraph*{%s}")
|
||
("\\subparagraph{%s}" . "\\subparagraph*{%s}"))
|
||
("article-1+2+3"
|
||
"\\documentclass{article}
|
||
[NO-DEFAULT-PACKAGES]
|
||
[PACKAGES]
|
||
[EXTRA]"
|
||
("\\section{%s}" . "\\section*{%s}")
|
||
("\\subsection{%s}" . "\\subsection*{%s}")
|
||
("\\subsubsection{%s}" . "\\subsubsection*{%s}")
|
||
("\\paragraph{%s}" . "\\paragraph*{%s}")
|
||
("\\subparagraph{%s}" . "\\subparagraph*{%s}"))
|
||
("report-1+2+3"
|
||
"\\documentclass[11pt]{report}
|
||
[NO-DEFAULT-PACKAGES]
|
||
[PACKAGES]
|
||
[EXTRA]"
|
||
("\\part{%s}" . "\\part*{%s}")
|
||
("\\chapter{%s}" . "\\chapter*{%s}")
|
||
("\\section{%s}" . "\\section*{%s}")
|
||
("\\subsection{%s}" . "\\subsection*{%s}")
|
||
("\\subsubsection{%s}" . "\\subsubsection*{%s}"))
|
||
("book-1+2+3"
|
||
"\\documentclass[11pt]{book}
|
||
[NO-DEFAULT-PACKAGES]
|
||
[PACKAGES]
|
||
[EXTRA]"
|
||
("\\part{%s}" . "\\part*{%s}")
|
||
("\\chapter{%s}" . "\\chapter*{%s}")
|
||
("\\section{%s}" . "\\section*{%s}")
|
||
("\\subsection{%s}" . "\\subsection*{%s}")
|
||
("\\subsubsection{%s}" . "\\subsubsection*{%s}")))))))
|
||
#+end_src
|
||
|
||
*** [[https://github.com/bdarcus/citar][Citar: citing bibliography]] with [[https://orgmode.org/][Org Mode]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:citing-bibliography
|
||
:END:
|
||
|
||
[[https://github.com/bdarcus/citar][Citar]] is a completing-read front-end to browse and act on BibTeX, BibLaTeX, as
|
||
well as CSL JSON bibliographic data with LaTeX, markdown, and org-cite editing
|
||
support. In combination with vertico, orderless, embark, marginalia, and
|
||
consult, [[https://github.com/bdarcus/citar][Citar]] provides quick filtering and selecting of bibliographic entries
|
||
from the minibuffer, as well as the option to run different commands on those
|
||
selections. Listing [[lst:configure-oc-cite+citar]] configures =org-cite=, =citar=,
|
||
and =org=.
|
||
|
||
#+caption[Configure =org-cite= with =citar=]:
|
||
#+caption: Configure =oc-cite= with =citar=.
|
||
#+name: lst:configure-oc-cite+citar
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'oc
|
||
(require 'oc-biblatex)
|
||
(require 'oc-csl)
|
||
|
||
(custom-set-variables
|
||
'(org-cite-export-processors '((latex biblatex)
|
||
(t csl)))
|
||
'(org-cite-global-bibliography '("~/VCS/research/refs.bib")))
|
||
|
||
(when (require 'citar nil 'noerror)
|
||
(custom-set-variables
|
||
'(org-cite-activate-processor 'citar)
|
||
'(org-cite-follow-processor 'citar)
|
||
'(org-cite-insert-processor 'citar))))
|
||
|
||
(with-eval-after-load 'org
|
||
(when (require 'citar nil 'noerror)
|
||
(custom-set-variables
|
||
'(citar-bibliography '("~/VCS/research/refs.bib"))
|
||
'(citar-file-extensions '("djvu" "pdf"))
|
||
'(citar-library-paths '("~/VCS/research/papers/"))))
|
||
|
||
(define-key org-mode-map (kbd "C-c b") #'org-cite-insert))
|
||
#+end_src
|
||
|
||
Ref. [cite:@Schulte.MCSE.2011.41] shows that [[https://orgmode.org/][Org-mode]] is a simple, plain-text
|
||
markup language for hierarchical documents allowing intermingling of data, code,
|
||
and prose. It serves as an example link to to show how to use [[https://github.com/bdarcus/citar][Citar]] within this
|
||
setup, provided that =citar-bibliography= and =citar-library-paths= point to
|
||
valid directories and files. In an [[https://orgmode.org/][Org-mode]] buffer this setup allows to:
|
||
1. Insert an [[https://orgmode.org/][Org-mode]] cite link:
|
||
1. Type {{{kbd(C-c b)}}} or {{{kbd(M-x org-cite-insert)}}}.
|
||
2. Navigate to the bibliographic entry to insert.
|
||
3. Select it.
|
||
2. View an electronic copy of an [[https://orgmode.org/][Org-mode]] cite link:
|
||
1. Move point to the [[https://orgmode.org/][Org-mode]] cite link.
|
||
2. Type {{{kbd(C-:)}}} or {{{kbd(M-x embark-dwim)}}}.
|
||
3. Navigate to the corresponding library file.
|
||
4. Select it.
|
||
3. Open the DOI of an [[https://orgmode.org/][Org-mode]] cite link:
|
||
1. Move point to the [[https://orgmode.org/][Org-mode]] cite link.
|
||
2. Type {{{kbd(C-:)}}} or {{{kbd(M-x embark-dwim)}}}.
|
||
3. Navigate to the corresponding link.
|
||
4. Select it.
|
||
|
||
*** TODO Compare bibtex and biblatex
|
||
1. [[https://www.economics.utoronto.ca/osborne/latex/BIBTEX.HTM][Using bibtex: a short guide]]
|
||
2. [[https://www.tug.org/texlive//devsrc/Master/texmf-dist/doc/latex/biblatex/biblatex.pdf][The biblatex package]]
|
||
3. [[https://github.com/yuchenlin/rebiber][Rebiber: A tool for normalizing bibtex with official info]]
|
||
4. [[https://github.com/josephwright/biblatex-phys][A biblatex implementation of the AIP and APS bibliography style]]
|
||
|
||
#+caption[Delete =Biber= cache to get rid of =Biber= exit code 2]:
|
||
#+caption: Delete =Biber= cache to get rid of =Biber= exit code 2.
|
||
#+name: lst:delete-biber-cache
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'emacs
|
||
;; https://tex.stackexchange.com/a/579356 answers
|
||
;; "How to solve Biber exiting with error code 2 but no error messages?"
|
||
(defun biber-delete-cache ()
|
||
"Delete the `Biber' cache to get rid of `Biber' exit code 2."
|
||
(cl-destructuring-bind (exit-code output)
|
||
(shell-command-with-exit-code "rm" "-rf" "$(biber --cache)")
|
||
(if (= 0 exit-code) (message "%s") (string-trim output)
|
||
(error "%s" (string-trim output))))))
|
||
#+end_src
|
||
|
||
*** [[info:org#Adding Hyperlink Types][Making Org hyperlink types (info)]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:making-org-hyperlink-types
|
||
:END:
|
||
|
||
Listing [[lst:org-ref-like-org-link-types]] defines =org-link= types for backwards
|
||
compatibility with [[https://github.com/jkitchin/org-ref][org-ref]]. Listing [[lst:define-org-pdfview-link-type]] uses ideas
|
||
from the definition of =docview-org-link= and =doi-org-link= types to define an
|
||
=pdfview-org-link= type for use with [[https://github.com/vedang/pdf-tools][pdf-tools]]. Finally, listing
|
||
[[lst:emacs-lisp-setup-patch-ol-info]] patches the function =org-info-export= and
|
||
listing [[lst:emacs-lisp-setup-buffer-local-ol-info]] sets the constants
|
||
~org-info-emacs-documents~ and ~org-info-other-documents~ as buffer local
|
||
variables in order to export the =info-org-link= types in this document to
|
||
=html= and LaTeX correctly.
|
||
|
||
#+caption[Define =org-link= types for backwards compatibility with =org-ref=]:
|
||
#+caption: Define =org-link= types for backwards compatibility with =org-ref=.
|
||
#+name: lst:org-ref-like-org-link-types
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'ol
|
||
(org-link-set-parameters
|
||
"ac*" :export (lambda (path _desc backend _info)
|
||
(pcase backend
|
||
(`latex (format "\\gls*{%s}" path))
|
||
(_ path))))
|
||
(org-link-set-parameters
|
||
"cite" :export (lambda (path _desc backend _info)
|
||
(pcase backend
|
||
(`latex (format "\\cite{%s}" path))
|
||
(_ path))))
|
||
(org-link-set-parameters
|
||
"eqref" :export (lambda (path _desc backend _info)
|
||
(pcase backend
|
||
(`latex (format "\\eqref{%s}" path))
|
||
(_ path))))
|
||
(org-link-set-parameters
|
||
"hyperlink" :export (lambda (path desc backend _info)
|
||
(pcase backend
|
||
(`latex (format "\\hyperlink{%s}{%s}" path desc))
|
||
(_ path))))
|
||
(org-link-set-parameters
|
||
"label" :export (lambda (path _desc backend _info)
|
||
(pcase backend
|
||
(`latex (format "\\label{%s}" path))
|
||
(_ path))))
|
||
(org-link-set-parameters
|
||
"ref" :export (lambda (path _desc backend _info)
|
||
(pcase backend
|
||
(`latex (format "\\ref{%s}" path))
|
||
(_ path)))))
|
||
#+end_src
|
||
|
||
#+caption[Define an =org-link= type for =pdf-tools=]:
|
||
#+caption: Define an =org-link= type for =pdf-tools=.
|
||
#+name: lst:define-org-pdfview-link-type
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'ol
|
||
(autoload 'pdf-view-goto-page "pdf-view" nil t)
|
||
(org-link-set-parameters "pdfview"
|
||
:follow #'org-pdfview-open
|
||
:export #'org-pdfview-export
|
||
:store #'org-pdfview-store-link)
|
||
|
||
(defun org-pdfview-export (link description backend _)
|
||
"Export a \"pdfview\" type link.
|
||
The paths of the links export as file relative paths in order to
|
||
facilate moving single directories or whole directory trees."
|
||
(let ((path (if (string-match "\\(.+\\)::.+" link)
|
||
(match-string 1 link)
|
||
link))
|
||
(desc (or description link)))
|
||
(when (stringp path)
|
||
(setq path (file-relative-name path))
|
||
(pcase backend
|
||
(`html (format "<a href=\"%s\">%s</a>" path desc))
|
||
(`latex (format "\\href{%s}{%s}" path desc))
|
||
(`ascii (format "%s (%s)" desc path))
|
||
(_ path)))))
|
||
|
||
(defun org-pdfview-open (link _)
|
||
"Open a \"pdfview\" type link."
|
||
(string-match "\\(.*?\\)\\(?:::\\([0-9]+\\)\\)?$" link)
|
||
(let ((path (match-string 1 link))
|
||
(page (and (match-beginning 2)
|
||
(string-to-number (match-string 2 link)))))
|
||
;; Let Org mode open the file (in-emacs = 1) to ensure
|
||
;; org-link-frame-setup is respected.
|
||
(org-open-file path 1)
|
||
(when page (pdf-view-goto-page page))))
|
||
|
||
(defun org-pdfview-store-link ()
|
||
"Store a \"pdfview\" type link."
|
||
(when (eq major-mode 'pdf-view-mode)
|
||
(let* ((path buffer-file-name)
|
||
(page (pdf-view-current-page))
|
||
(link (concat "pdfview:" path "::" (number-to-string page))))
|
||
(org-link-store-props
|
||
:type "pdfview"
|
||
:link link
|
||
:description path)))))
|
||
#+end_src
|
||
|
||
#+caption[Patch =ol-info=]:
|
||
#+caption: Patch =ol-info=.
|
||
#+name: lst:emacs-lisp-setup-patch-ol-info
|
||
#+begin_src emacs-lisp :exports code :silent
|
||
(with-eval-after-load 'ol-info
|
||
(defun org-info-export (path desc format)
|
||
"Export an info link.
|
||
See `org-link-parameters' for details about PATH, DESC and FORMAT."
|
||
(let* ((parts (split-string path "#\\|::"))
|
||
(manual (car parts))
|
||
(node (or (nth 1 parts) "Top")))
|
||
(pcase format
|
||
(`html
|
||
(format "<a href=\"%s#%s\">%s</a>"
|
||
(org-info-map-html-url manual)
|
||
(org-info--expand-node-name node)
|
||
(or desc path)))
|
||
(`latex
|
||
(format "\\href{%s\\#%s}{%s}"
|
||
(org-info-map-html-url manual)
|
||
(org-info--expand-node-name node)
|
||
(or desc path)))
|
||
(`texinfo
|
||
(let ((title (or desc "")))
|
||
(format "@ref{%s,%s,,%s,}" node title manual)))
|
||
(_ nil)))))
|
||
#+end_src
|
||
|
||
#+caption[Patch buffer local =ol-info=]:
|
||
#+caption: Patch buffer local =ol-info=.
|
||
#+name: lst:emacs-lisp-setup-buffer-local-ol-info
|
||
#+begin_src emacs-lisp :exports code :silent :tangle no
|
||
(with-eval-after-load 'ol-info
|
||
(make-variable-buffer-local 'org-info-emacs-documents)
|
||
(setq org-info-emacs-documents (delete "org" org-info-emacs-documents))
|
||
(make-variable-buffer-local 'org-info-other-documents)
|
||
(setq org-info-other-documents
|
||
(cl-union '(("consult" . "https://github.com/minad/consult")
|
||
("embark" . "https://github.com/oantolin/embark")
|
||
("marginalia" . "https://github.com/minad/marginalia")
|
||
("org" . "https://orgmode.org/org.html")
|
||
("orderless" . "https://github.com/oantolin/orderless")
|
||
("sly" . "https://joaotavora.github.io/sly/")
|
||
("vertico" . "https://github.com/minad/vertico"))
|
||
org-info-other-documents :test #'equal)))
|
||
#+end_src
|
||
*** [[https://tecosaur.github.io/emacs-config/#translate-capital-keywords][Translate capital keywords (old) to lower case (new)]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:convert-upper-to-lower-case-keywords
|
||
:END:
|
||
|
||
#+caption[Convert upper to lower case keywords]:
|
||
#+caption: Convert upper to lower case keywords.
|
||
#+name: lst:convert-upper-to-lower-case-keywords
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'emacs
|
||
;; https://tecosaur.github.io/emacs-config/#translate-capital-keywords
|
||
(defun org-syntax-convert-keyword-case-to-lower ()
|
||
"Convert all #+KEYWORDS to #+keywords."
|
||
(interactive)
|
||
(when (derived-mode-p 'org-mode)
|
||
(save-excursion
|
||
(goto-char (point-min))
|
||
(let ((count 0)
|
||
(case-fold-search nil))
|
||
(while (re-search-forward "^[ \t]*#\\+[A-Z_]+" nil t)
|
||
(unless (s-matches-p "RESULTS" (match-string 0))
|
||
(replace-match (downcase (match-string 0)) t)
|
||
(setq count (1+ count))))
|
||
(message "Replaced %d keywords" count))))))
|
||
#+end_src
|
||
|
||
*** [[https://lists.gnu.org/archive/html/emacs-orgmode/2016-07/msg00394.html][Evaluate specific source blocks at load-time]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:load-time-specific-source-block-evaluation
|
||
:END:
|
||
|
||
[[https://emacs.stackexchange.com/questions/12938/how-can-i-evaluate-elisp-in-an-orgmode-file-when-it-is-opened][How to do load time source block evaluation]]
|
||
|
||
#+caption[Evaluate specific source blocks at load-time]:
|
||
#+caption: Evaluate specific source blocks at load-time.
|
||
#+name: lst:load-time-specific-source-block-evaluation
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'emacs
|
||
(defun org-eval-named-blocks-with-infix (infix)
|
||
"Evaluate all source blocks having INFIX in their name."
|
||
(when (eq major-mode 'org-mode)
|
||
(let ((blocks
|
||
(org-element-map
|
||
(org-element-parse-buffer 'greater-element nil) 'src-block
|
||
(lambda (block)
|
||
(when-let ((name (org-element-property :name block)))
|
||
(when (string-match-p infix name) block))))))
|
||
(dolist (block blocks)
|
||
(goto-char (org-element-property :begin block))
|
||
(org-babel-execute-src-block)))))
|
||
|
||
(defun org-eval-emacs-lisp-setup-blocks ()
|
||
"Evaluate all source blocks having \"emacs-lisp-setup\" in their name."
|
||
(interactive)
|
||
(org-eval-named-blocks-with-infix "emacs-lisp-setup"))
|
||
|
||
(defun org-eval-python-setup-blocks ()
|
||
"Evaluate all source blocks having \"python-setup\" in their name."
|
||
(interactive)
|
||
(org-eval-named-blocks-with-infix "python-setup"))
|
||
|
||
;; Emacs looks for "Local variables:" after the last "newline-formfeed".
|
||
(add-to-list 'safe-local-eval-forms '(org-eval-emacs-lisp-setup-blocks)))
|
||
|
||
(with-eval-after-load 'emacs
|
||
(defun my-org-eval-blocks-named (infix)
|
||
"Evaluate all source blocks having INFIX in their name."
|
||
(when (eq major-mode 'org-mode)
|
||
(let ((blocks
|
||
(org-element-map
|
||
(org-element-parse-buffer 'greater-element nil) 'src-block
|
||
(lambda (block)
|
||
(when-let ((name (org-element-property :name block)))
|
||
(when (string-match-p infix name) block))))))
|
||
(dolist (block blocks)
|
||
(goto-char (org-element-property :begin block))
|
||
(org-babel-execute-src-block)))))
|
||
|
||
;; Emacs looks for "Local variables:" after the last "newline-formfeed".
|
||
(add-to-list 'safe-local-eval-forms
|
||
'(apply 'my-org-eval-blocks-named '("emacs-lisp-setup"))))
|
||
#+end_src
|
||
|
||
*** [[info:org#LaTeX header and sectioning][Easy LaTeX preamble editing]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:easy-latex-preamble-editing
|
||
:END:
|
||
|
||
There are at least two ways (new and old) to edit the LateX preamble
|
||
=latex_header= and =latex-extra_header= export options easily in LaTeX source or
|
||
export blocks. This [[info:org#Top][Org (info)]] file uses the new way, but keeps the old way for
|
||
backwards compatibility.
|
||
|
||
The new way -- exploiting an idea of [[https://www.matem.unam.mx/~omar/][Omar Antolin Camarena]] -- is to code new
|
||
[[info:org#Editing Source Code][<LANGUAGE>-modes]] allowing to edit in LaTeX mode and to export to LaTeX code with
|
||
[[info:org#LaTeX specific export settings][correct LaTeX preamble export setting prefixes]]. Here, are links to three posts
|
||
exposing his idea:
|
||
1. [[https://www.reddit.com/r/orgmode/comments/7u2n0h/tip_for_defining_latex_macros_for_use_in_both/][Export LaTeX macros to LaTeX and HTML/MathJax preambles (reddit)]],
|
||
2. [[https://www.reddit.com/r/orgmode/comments/5bi6ku/tip_for_exporting_javascript_source_block_to/][Export JavaScript source blocks to script tags in HTML (reddit)]],
|
||
3. [[https://emacs.stackexchange.com/questions/28301/export-javascript-source-block-to-script-tag-in-html-when-exporting-org-file-to][Export JavaScript source blocks to script tags in HTML (SX)]].
|
||
Listing [[lst:emacs-lisp-setup-latex-header]] implements this way by means of two
|
||
new [[info:org#Editing Source Code][<LANGUAGE>-modes]]: =latex-header= and =latex-extra-header=.
|
||
|
||
#+caption[New =<LANGUAGE>-modes= to edit the LaTeX preamble easily]:
|
||
#+caption: Add =latex-header= and =latex-extra-header= language modes to edit
|
||
#+caption: LaTeX preamble =latex_header= and =latex_extra_header= export options
|
||
#+caption: easily.
|
||
#+name: lst:emacs-lisp-setup-latex-header
|
||
#+begin_src emacs-lisp :exports code :silent
|
||
(with-eval-after-load 'emacs
|
||
(defun prefix-all-lines (prefix body)
|
||
(with-temp-buffer
|
||
(insert body)
|
||
(string-insert-rectangle (point-min) (point-max) prefix)
|
||
(buffer-string)))
|
||
|
||
(defun org-babel-execute:latex-extra-header (body _params)
|
||
"Execute a block of LaTeX extra header lines with org-babel.
|
||
This function is called by `org-babel-execute-src-block' and
|
||
prefixes all lines with \"#+latex_extra_header: \"."
|
||
(prefix-all-lines "#+latex_extra_header: " body))
|
||
|
||
(defun org-babel-execute:latex-header (body _params)
|
||
"Execute a block of LaTeX header lines with org-babel.
|
||
This function is called by `org-babel-execute-src-block' and
|
||
prefixes all lines with \"#+latex_header: \"."
|
||
(prefix-all-lines "#+latex_header: " body))
|
||
|
||
(defvar org-babel-default-header-args:latex-extra-header
|
||
'((:exports . "results") (:results . "raw")))
|
||
|
||
(defvar org-babel-default-header-args:latex-header
|
||
'((:exports . "results") (:results . "raw")))
|
||
|
||
(with-eval-after-load 'org-src
|
||
(custom-set-variables
|
||
'(org-src-window-setup 'current-window))
|
||
|
||
(add-to-list 'org-src-lang-modes '("toml" . conf-toml))
|
||
(add-to-list 'org-src-lang-modes '("latex-header" . latex))
|
||
(add-to-list 'org-src-lang-modes '("latex-extra-header" . latex))))
|
||
#+end_src
|
||
|
||
The old way is to use a special export attribute as in the function
|
||
=org-latex-header-blocks-filter= in [[https://git.sr.ht/~bzg/org-contrib/tree/master/item/lisp/ox-extra.el][ox-extra.el]]. Apparently, nobody is using
|
||
this broken function (broken, since it relies on support only in org-mode before
|
||
=2014-11-11=). Listing [[lst:org-latex-header-blocks-filter]] proposes a fix for
|
||
=org-latex-header-blocks-filter=.
|
||
|
||
#+caption[Convert marked LaTeX export blocks to LaTeX header lines]:
|
||
#+caption: Convert marked LaTeX export blocks to LaTeX header lines.
|
||
#+name: lst:org-latex-header-blocks-filter
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'ox
|
||
(defun org-latex-header-blocks-filter (backend)
|
||
"Convert marked LaTeX export blocks to \"#+latex_header: \" lines.
|
||
The marker is a line \"#+header: :header yes\" preceding the block.
|
||
|
||
For instance, the LaTeX export block
|
||
|
||
,#+header: :header yes
|
||
,#+begin_export latex
|
||
% This line converts to a LaTeX header line.
|
||
,#+end_export
|
||
|
||
converts to
|
||
|
||
\"#+latex_header: % This line converts to a LaTeX header line.\"."
|
||
(when (org-export-derived-backend-p backend 'latex)
|
||
(let ((blocks
|
||
(org-element-map
|
||
(org-element-parse-buffer 'greater-element nil) 'export-block
|
||
(lambda (block)
|
||
(let ((type (org-element-property :type block))
|
||
(header (org-export-read-attribute :header block :header)))
|
||
(when (and (string= type "LATEX") (string= header "yes"))
|
||
block))))))
|
||
(mapc (lambda (block)
|
||
;; Set point to where to insert LaTeX header lines
|
||
;; after deleting the block.
|
||
(goto-char (org-element-property :post-affiliated block))
|
||
(let ((lines
|
||
(split-string (org-element-property :value block) "\n")))
|
||
(delete-region (org-element-property :begin block)
|
||
(org-element-property :end block))
|
||
(dolist (line lines)
|
||
(insert (concat "#+latex_header: "
|
||
(replace-regexp-in-string "\\` *" "" line)
|
||
"\n")))))
|
||
;; Reverse to go upwards to avoid wrecking the list of
|
||
;; block positions in the file that would occur in case
|
||
;; of going downwards.
|
||
(reverse blocks)))))
|
||
|
||
;; Push the filter on the hook.
|
||
(cl-pushnew #'org-latex-header-blocks-filter
|
||
org-export-before-parsing-hook))
|
||
#+end_src
|
||
|
||
This file uses the new way, while keeping the old way for backwards
|
||
compatibility, because the new way feels less hackish than the old way. A
|
||
practical difference is that new way source blocks (contrary to old way export
|
||
blocks) do not work in [[info:org#Export Settings][#+SETUPFILE: <FILE>]], but only in [[info:org#Export Settings][#+INCLUDE: <FILE>]] files.
|
||
|
||
*** [[info:org#Export Settings][#+INCLUDE: <FILE> (info)]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:include-file-usage
|
||
:END:
|
||
|
||
Evaluation of the source block in listing
|
||
[[lst:make-source-block-with-export-keyword-settings]] produces the source block
|
||
that exports to listing [[lst:source-file-export-keyword-settings]] in order to show
|
||
the first nine lines of this [[file:README.org]] file. The last line shows that
|
||
[[file:include.org][include.org]] is the argument for [[info:org#Export Settings][#+INCLUDE: <FILE>]].
|
||
|
||
#+caption[Make setup and include file export keyword settings source block]:
|
||
#+caption: The shell script to make the source block containing the export
|
||
#+caption: keyword settings.
|
||
#+name: lst:make-source-block-with-export-keyword-settings
|
||
#+begin_src shell :exports both :results drawer
|
||
echo "#+caption[Source file export keyword settings]:"
|
||
echo "#+caption: The first nine lines of README.org containing the export"
|
||
echo "#+caption: keyword settings."
|
||
echo "#+name: lst:source-file-export-keyword-settings"
|
||
echo "#+begin_src org :tangle no"
|
||
head -n 9 README.org
|
||
echo -n "#+end_src"
|
||
#+end_src
|
||
|
||
#+RESULTS: lst:make-source-block-with-export-keyword-settings
|
||
:results:
|
||
#+caption[Source file export keyword settings]:
|
||
#+caption: The first nine lines of README.org containing the export
|
||
#+caption: keyword settings.
|
||
#+name: lst:source-file-export-keyword-settings
|
||
#+begin_src org :tangle no
|
||
#+title: Emacs setup for use with LaTeX, Org, and Python
|
||
#+author: Gerard Vermeulen
|
||
#+babel: :cache no
|
||
#+latex_class: article-local
|
||
#+latex_class_options: [11pt,a4paper,english,svgnames,tables]
|
||
#+macro: kbd (eval (by-backend-kbd-org-macro $1))
|
||
#+property: header-args:emacs-lisp :exports code :results silent :tangle init.el
|
||
#+property: header-args:org :tangle include.org
|
||
#+startup: content
|
||
#+end_src
|
||
:end:
|
||
|
||
Listing [[lst:by-backend-kbd-org-macro]] defines the tools for the definition of the
|
||
[[https://orgmode.org/][Org mode]] =kbd= macro on the fifth line of listing
|
||
[[lst:source-file-export-keyword-settings]].
|
||
|
||
#+attr_latex: :options breaklines
|
||
#+caption[Define the tools of the =Org-mode= =kbd= macro]:
|
||
#+caption: Define the tools for the =Org-mode= =kbd= macro.
|
||
#+name: lst:by-backend-kbd-org-macro
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'emacs
|
||
(autoload 'htmlize-protect-string "htmlize" nil t)
|
||
|
||
;; https://orgmode.org/worg/org-contrib/babel/languages/ob-doc-LaTeX.html#orge5c50fd
|
||
(defmacro by-backend (&rest body)
|
||
"Help for org-export backend dependent execution."
|
||
`(cl-case ',(bound-and-true-p org-export-current-backend) ,@body))
|
||
|
||
(defun by-backend-kbd-org-macro (keys)
|
||
"Help for an org-export backend dependent \"#+macro: kbd\"."
|
||
(by-backend
|
||
(html (format "@@html:<kbd>%s</kbd>@@" (htmlize-protect-string keys)))
|
||
(latex (format "@@latex:\\colorbox{PowderBlue}{\\texttt{%s}}@@" keys)))))
|
||
#+end_src
|
||
|
||
Listing [[lst:use-latex-header-1]], [[lst:use-latex-header-2]], [[lst:use-latex-header-3]],
|
||
[[lst:use-latex-header-4]], and [[lst:use-latex-header-5]] tangle into the
|
||
[[file:include.org][include.org]] file in order to create the [[https://www.latex-project.org/][LaTeX]] preamble.
|
||
|
||
#+caption[LaTeX preamble: replacing the =Org-mode= default packages]:
|
||
#+caption: LaTeX preamble: replacing the =Org-mode= default packages.
|
||
#+name: lst:use-latex-header-1
|
||
#+begin_src org
|
||
,#+begin_src latex-header
|
||
% LuaLaTeX-, PdfLaTeX-, or XeTeX-COMPILER COMPATIBILITY:
|
||
% Prevent collisions by using font packages before compiler specific packages.
|
||
\usepackage{ifthen,ifluatex,ifxetex}
|
||
\ifthenelse{\boolean{luatex}}{
|
||
\usepackage{fontspec} % lualatex
|
||
}{\ifthenelse{\boolean{xetex}}{
|
||
\usepackage{mathspec} % xetex
|
||
}{
|
||
\usepackage[T1]{fontenc} % pdflatex
|
||
\usepackage[utf8]{inputenc} % pdflatex
|
||
}
|
||
}
|
||
\usepackage{amsmath}
|
||
\usepackage{amssymb}
|
||
\usepackage{pifont} % check mark (\ding{52}) and cross mark (\ding{56})
|
||
\usepackage{textcomp} % \texttimes
|
||
\usepackage{wasysym} % \diameter
|
||
|
||
% Org-mode REQUIREMENTS:
|
||
\usepackage{graphicx}
|
||
\usepackage{longtable}
|
||
\usepackage{wrapfig}
|
||
\usepackage{rotating}
|
||
\usepackage[normalem]{ulem}
|
||
\usepackage{capt-of}
|
||
\usepackage{hyperref}
|
||
|
||
,#+end_src
|
||
#+end_src
|
||
|
||
#+caption[LaTeX preamble: language, lists and floats]:
|
||
#+caption: LaTeX preamble: language, lists and floats.
|
||
#+name: lst:use-latex-header-2
|
||
#+begin_src org
|
||
,#+begin_src latex-header
|
||
% LANGUAGE:
|
||
\usepackage{babel}
|
||
\usepackage{fvextra}
|
||
\usepackage{csquotes}
|
||
|
||
% LISTS:
|
||
\usepackage{enumitem}
|
||
\setlist{noitemsep}
|
||
|
||
% LISTINGS:
|
||
% Section 2.6 of caption-eng.pdf (texdoc caption) explains that the sign
|
||
% of "skip" depends on the assumption "position=above" or "position=below".
|
||
% The assumption should match the real caption position in the LaTeX code.
|
||
\usepackage{caption}
|
||
\usepackage[newfloat]{minted}
|
||
\captionsetup[listing]{position=below,skip=0em}
|
||
\usemintedstyle{xcode}
|
||
|
||
% TABLES:
|
||
% https://tex.stackexchange.com/questions/341205/
|
||
% what-is-the-difference-between-tabular-tabular-and-tabularx-environments
|
||
% https://emacs.stackexchange.com/questions/26179/
|
||
% change-org-mode-table-style-just-for-latex-export
|
||
% https://tex.stackexchange.com/questions/468585/
|
||
% table-formatting-using-siunitx
|
||
\usepackage{booktabs}
|
||
\usepackage{colortbl}
|
||
\usepackage{tabularx} % DANGER: beware of Org table :width and :align options!
|
||
|
||
,#+end_src
|
||
#+end_src
|
||
|
||
#+caption[LaTeX preamble: page layout]:
|
||
#+caption: LaTeX preamble: page layout.
|
||
#+name: lst:use-latex-header-3
|
||
#+begin_src org
|
||
,#+begin_src latex-header
|
||
% PAGE LAYOUT:
|
||
\usepackage{fancyhdr}
|
||
\usepackage{lastpage}
|
||
\usepackage[
|
||
headheight=20mm,
|
||
top=40mm,
|
||
bottom=20mm,
|
||
left=60pt,
|
||
right=60pt,
|
||
heightrounded,
|
||
verbose,
|
||
]{geometry}
|
||
|
||
% TECHNICS:
|
||
\usepackage{siunitx}
|
||
\usepackage{tikz}
|
||
|
||
,#+end_src
|
||
#+end_src
|
||
|
||
#+caption[LaTeX preamble: float barriers]:
|
||
#+caption: LaTeX preamble: float barriers.
|
||
#+name: lst:use-latex-header-4
|
||
#+begin_src org
|
||
,#+begin_src latex-header
|
||
% FLOAT BARRIERS:
|
||
% https://tex.stackexchange.com/questions/118662/use-placeins-for-subsections
|
||
% Make section an implicit float barrier:
|
||
\usepackage[section]{placeins}
|
||
% Make subsection an implicit float barrier:
|
||
\makeatletter
|
||
\AtBeginDocument{%
|
||
\expandafter\renewcommand\expandafter\subsection\expandafter{%
|
||
\expandafter\@fb@secFB\subsection
|
||
}%
|
||
}
|
||
\makeatother
|
||
% Make subsubsection an implicit float barrier:
|
||
\makeatletter
|
||
\AtBeginDocument{%
|
||
\expandafter\renewcommand\expandafter\subsubsection\expandafter{%
|
||
\expandafter\@fb@secFB\subsubsection
|
||
}%
|
||
}
|
||
\makeatother
|
||
|
||
,#+end_src
|
||
#+end_src
|
||
|
||
#+caption[LaTeX preamble: fancy headers and footers]:
|
||
#+caption: LaTeX preamble: fancy headers and footers.
|
||
#+name: lst:use-latex-header-5
|
||
#+begin_src org
|
||
,#+begin_src latex-header
|
||
% FANCY HEADERS AND FOOTERS:
|
||
% Add fancy headers and footers to normal pages.
|
||
\pagestyle{fancy}
|
||
\fancyhf{}
|
||
\renewcommand{\footrulewidth}{0.4pt}
|
||
\fancyfoot[C]{\emph{
|
||
Emacs setup for use with \LaTeX{}, Org, and Python -- Gerard Vermeulen}}
|
||
\renewcommand{\headrulewidth}{0.4pt}
|
||
\fancyhead[L]{\includegraphics[height=1.8cm]{Org-mode-unicorn.png}}
|
||
\fancyhead[C]{
|
||
Page: \thepage/\pageref{LastPage} \\
|
||
\text{ } \\
|
||
\text{ } \\
|
||
DRAFT
|
||
}
|
||
\fancyhead[R]{\includegraphics[height=1.8cm]{Emacs-logo.png}}
|
||
|
||
% Add fancy header and footer to custom titlepage.
|
||
% https://tex.stackexchange.com/questions/506102/
|
||
% adding-header-and-footer-to-custom-titlepage
|
||
\fancypagestyle{titlepage}{%
|
||
\fancyhf{}
|
||
\renewcommand{\footrulewidth}{0.4pt}
|
||
\fancyfoot[C]{\emph{
|
||
Emacs setup for use with \LaTeX{}, Org, and Python -- Gerard Vermeulen}}
|
||
\renewcommand{\headrulewidth}{0.4pt}
|
||
\fancyhead[L]{\includegraphics[height=1.8cm]{Org-mode-unicorn.png}}
|
||
\fancyhead[C]{
|
||
\pageref{LastPage} pages \\
|
||
\text{ } \\
|
||
\text{ } \\
|
||
DRAFT
|
||
}
|
||
\fancyhead[R]{\includegraphics[height=1.8cm]{Emacs-logo.png}}
|
||
}
|
||
% #+latex_header: END.
|
||
,#+end_src
|
||
#+end_src
|
||
|
||
*** [[info:org#LaTeX specific export settings][Advanced LaTeX export settings]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:advanced-latex-export-settings
|
||
:END:
|
||
|
||
Listing [[lst:ox-latex-emacs-lisp-setup]] initializes the buffer local variables
|
||
=org-latex-classes=, =org-latex-title-command=, =org-latex-toc-command=, and
|
||
=org-latex-subtitle-format=. Listing [[lst/title-page]] is a template to initialize
|
||
=org-latex-title-command=. Type {{{kbd(M-x org-latex-classes)}}}, {{{kbd(M-x
|
||
org-latex-subtitle-format)}}}, {{{kbd(M-x org-latex-title-command)}}}, and
|
||
{{{kbd(M-x org-latex-toc-command)}}} to read how those variables control
|
||
exporting from Org-mode to LaTeX.
|
||
|
||
#+caption[Define buffer local =ox-latex= variables]:
|
||
#+caption: Define buffer local =-ox-latex= variables.
|
||
#+header: :var title-page=lst/title-page
|
||
#+name: lst:ox-latex-emacs-lisp-setup
|
||
#+begin_src emacs-lisp :results silent :tangle no
|
||
(when (require 'ox-latex nil 'noerror)
|
||
;; https://emacs.stackexchange.com/questions/47347/
|
||
;; customizing-org-latex-title-command-to-edit-title-page
|
||
(make-variable-buffer-local 'org-latex-classes)
|
||
(cl-pushnew '("article-local"
|
||
"\\documentclass[11pt]{article}
|
||
[NO-DEFAULT-PACKAGES]
|
||
[PACKAGES]
|
||
[EXTRA]"
|
||
("\\section{%s}" . "\\section*{%s}")
|
||
("\\subsection{%s}" . "\\subsection*{%s}")
|
||
("\\subsubsection{%s}" . "\\subsubsection*{%s}")
|
||
("\\paragraph{%s}" . "\\paragraph*{%s}")
|
||
("\\subparagraph{%s}" . "\\subparagraph*{%s}"))
|
||
org-latex-classes :key #'car :test #'equal)
|
||
|
||
(make-variable-buffer-local 'org-latex-title-command)
|
||
(setq org-latex-title-command (concat title-page))
|
||
|
||
(make-variable-buffer-local 'org-latex-toc-command)
|
||
(setq org-latex-toc-command "
|
||
\\tableofcontents\\label{toc}
|
||
\\listoftables
|
||
\\listoffigures
|
||
\\newpage
|
||
")
|
||
|
||
(make-variable-buffer-local 'org-latex-subtitle-format)
|
||
(setq org-latex-subtitle-format ""))
|
||
#+end_src
|
||
|
||
#+caption[Show a title-page example for =org-latex-title-command=]:
|
||
#+caption: Show a title-page example for =org-latex-title-command=.
|
||
#+name: lst/title-page
|
||
#+begin_src latex :exports code :results silent :tangle no
|
||
\begin{titlepage}
|
||
%% https://tex.stackexchange.com/questions/506102/
|
||
%% adding-header-and-footer-to-custom-titlepage
|
||
\thispagestyle{titlepage}
|
||
\begin{center}
|
||
%% Title
|
||
\begin{Huge}
|
||
{\bf %t} \\
|
||
\vspace{1em}
|
||
\end{Huge}
|
||
%% Author
|
||
\begin{Large}
|
||
{\bf %a} \\
|
||
\vspace{1em}
|
||
\end{Large}
|
||
\end{center}
|
||
\end{titlepage}
|
||
#+end_src
|
||
|
||
*** [[https://orgmode.org/worg/dev/org-syntax-edited.html][Org Syntax]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:org-syntax
|
||
:END:
|
||
|
||
Two tools to grok how [[https://orgmode.org/worg/dev/org-element-api.html][Org mode parsing]] works are the [[https://orgmode.org/worg/dev/org-syntax-edited.html][Org Syntax]] specification
|
||
and the [[http://xahlee.info/emacs/emacs/elisp_parse_org_mode.html][Org mode parser tutorial]]. The [[https://orgmode.org/worg/dev/org-element-api.html][Org element parsing API]] boils down to three
|
||
functions:
|
||
1. The function [[https://orgmode.org/worg/dev/org-element-api.html#global][~org-element-parse-buffer~]] implements a fully recursive buffer
|
||
parser that returns an abstract syntax tree.
|
||
2. The functions [[https://orgmode.org/worg/dev/org-element-api.html#local][~org-element-at-point~ and ~org-element-context~]] return
|
||
information on the document structure around point either at the element
|
||
level or at the object level in case of ~org-element-context~.
|
||
Listing [[lst:grok-org-element-tree]] improves the [[http://xahlee.info/emacs/emacs/elisp_parse_org_mode.html][Org mode parser tutorial]] by
|
||
defining interactive wrappers that pretty print the results of those
|
||
non-interactive =org-element= functions to an =Emacs-lisp= buffer.
|
||
|
||
#+caption[Grok how =org-element= parses your document]:
|
||
#+caption: Grok how =org-element= parses your document.
|
||
#+name: lst:grok-org-element-tree
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'org-element
|
||
(when (autoload 'pp-display-expression "pp")
|
||
(defconst grok-org-output
|
||
"*Grok Org Element Output*"
|
||
"Grok Org output buffer name.")
|
||
|
||
(defun grok-org-element-at-point ()
|
||
(interactive)
|
||
(pp-display-expression
|
||
(org-element-at-point) grok-org-output))
|
||
|
||
(defun grok-org-element-context ()
|
||
(interactive)
|
||
(pp-display-expression
|
||
(org-element-context) grok-org-output))
|
||
|
||
(defun grok-org-element-parse-buffer ()
|
||
(interactive)
|
||
(let ((what (completing-read
|
||
"granularity: "
|
||
'(headline element greater-element object)
|
||
nil 'require-match)))
|
||
(pp-display-expression
|
||
(org-element-parse-buffer what) grok-org-output)))
|
||
|
||
(defun grok-org-heading-components ()
|
||
(interactive)
|
||
(pp-display-expression
|
||
(org-heading-components) grok-org-output))))
|
||
#+end_src
|
||
|
||
** Grammar, spelling, and style tools
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:writing-tools
|
||
:END:
|
||
|
||
*** [[https://wordnet.princeton.edu/][Wordnet]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:writing-wordnet
|
||
:END:
|
||
|
||
The [[https://github.com/gromnitsky/wordnut#readme][wordnut]] package is a major mode interface to [[https://wordnet.princeton.edu/][Wordnet]], a lexical database for
|
||
the English language. Listing [[lst:check-wordnut]] checks whether the system meets
|
||
the [[https://github.com/gromnitsky/wordnut#readme][wordnut]] prerequisites.
|
||
|
||
#+caption[System check for =wordnut=]:
|
||
#+caption: System check for =wordnut=.
|
||
#+name: lst:check-wordnut
|
||
#+begin_src emacs-lisp
|
||
(when (and (ensure-package-installation 'wordnut)
|
||
(executable-find "wn"))
|
||
(message "`wordnut' fails to find the `wn' executable"))
|
||
#+end_src
|
||
|
||
*** [[https://github.com/bnbeckwith/writegood-mode#readme][Writegood mode]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:writing-writegood-mode
|
||
:END:
|
||
|
||
[[https://github.com/bnbeckwith/writegood-mode#readme][Writegood mode]] is a minor mode to aid in finding common writing problems. [[http://matt.might.net/articles/shell-scripts-for-passive-voice-weasel-words-duplicates/][Matt
|
||
Might's "My Ph.D. advisor rewrote himself in bash" scripts]] inspired this mode.
|
||
Listing [[lst:configure-writegood-mode]] configures [[https://github.com/bnbeckwith/writegood-mode#readme][writegood mode]].
|
||
|
||
#+caption[Configure =writegood-mode=]:
|
||
#+caption: Configure =writegood-mode=.
|
||
#+name: lst:configure-writegood-mode
|
||
#+begin_src emacs-lisp
|
||
(when (and (ensure-package-installation 'writegood-mode)
|
||
(fboundp 'writegood-mode))
|
||
(global-set-key (kbd "C-c g") #'writegood-mode))
|
||
#+end_src
|
||
|
||
* Programming
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:programming
|
||
:END:
|
||
|
||
** [[https://github.com/lassik/emacs-format-all-the-code#readme][Format-all]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:format-all
|
||
:END:
|
||
|
||
Listing [[lst:configure-format-all]]:
|
||
1. Configures [[https://github.com/lassik/emacs-format-all-the-code#readme][format-all]] which is a package that provides an universal interface
|
||
to code formatters of more than 60 computer languages.
|
||
2. Adds =format-all-org-babel-post-tangle= to =org-babel-post-tangle-hook= to
|
||
format tangled Python code.
|
||
|
||
#+caption[Configure =format-all=]:
|
||
#+caption: Configure =format-all=.
|
||
#+name: lst:configure-format-all
|
||
#+begin_src emacs-lisp
|
||
;; https://github.com/lassik/emacs-format-all-the-code#readme
|
||
;; https://ianyepan.github.io/posts/format-all/
|
||
;; https://jamesaimonetti.com/posts/formatting-tangled-output-in-org-mode/
|
||
(when (and (ensure-package-installation 'format-all)
|
||
(fboundp 'format-all-ensure-formatter))
|
||
(add-hook 'prog-mode-hook #'format-all-ensure-formatter)
|
||
(add-hook
|
||
'org-babel-post-tangle-hook
|
||
(defun format-all-org-babel-post-tangle ()
|
||
(when (derived-mode-p 'python-mode)
|
||
(setq-local format-all-formatters '(("Python" black)))
|
||
(format-all-buffer)
|
||
(save-buffer)
|
||
(message "Saved reformatted tangled buffer `%s'" (buffer-file-name))))))
|
||
#+end_src
|
||
|
||
** [[https://dept-info.labri.fr/~strandh/Teaching/PFS/Common/Strandh-Tutorial/Dir-symbolic.html][Common Lisp programming]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:common-lisp-programming
|
||
:END:
|
||
Listing [[lst:configure-sly]] configures the [[info:sly#Top][Sly (info)]] Common Lisp IDE for Emacs
|
||
for use with [[http://www.sbcl.org/][Steel Bank Common Lisp (sbcl)]]:
|
||
1. It configures =sly-default-lisp= and =sly-lisp-implementations= as in the ~sly~ documentation string instead of in the [[info:sly#Multiple Lisps][multiple lisps (info)]] manual.
|
||
2. It ensures the [[info:sly#Auto-SLY][automatic connection to the lisp server (info)]] when opening a
|
||
Common Lisp file.
|
||
3. It configures searching documentation in the [[http://www.lispworks.com/documentation/HyperSpec/Front/][Common Lisp HyperSpec]] according
|
||
to the [[info:sly#Basic customization][basic customization (info)]] manual.
|
||
Finally, listing [[lst:configure-sly]] uses a technique to [[info:sly#Loading Slynk faster][load Slynk faster (info)]]
|
||
by means of a custom core file in src_emacs-lisp{no-littering-var-directory}.
|
||
Listing [[lst:sbcl-core-for-sly]] tangles to a script to dump such a [[http://www.sbcl.org/][SBCL]] core.
|
||
|
||
#+caption[Configure =sly=]:
|
||
#+caption: Configure =sly=.
|
||
#+name: lst:configure-sly
|
||
#+begin_src emacs-lisp
|
||
(when (ensure-package-installation 'sly)
|
||
(with-eval-after-load 'sly
|
||
(custom-set-variables
|
||
;; Customize `sly-default-lisp' instead of `inferior-lisp-program',
|
||
;; because `sly' uses `inferior-lisp-program' only as a backwards
|
||
;; compatibility fallback option.
|
||
'(sly-default-lisp 'sbcl)
|
||
`(sly-lisp-implementations
|
||
'((sbcl (,(executable-find "sbcl")
|
||
"--core"
|
||
,(no-littering-expand-var-file-name "sbcl.core-for-sly"))))))
|
||
|
||
(add-hook 'sly-mode-hook
|
||
(defun on-sly-mode-hook ()
|
||
(unless (sly-connected-p)
|
||
(save-excursion (sly)))))
|
||
|
||
(cond
|
||
((eq system-type 'darwin)
|
||
(setq common-lisp-hyperspec-root
|
||
"file:///usr/local/share/doc/hyperspec/HyperSpec/")
|
||
(setq common-lisp-hyperspec-symbol-table
|
||
(concat common-lisp-hyperspec-root "Data/Map_Sym.txt")))
|
||
((eq system-type 'gnu/linux)
|
||
(setq common-lisp-hyperspec-root
|
||
"file:///usr/share/doc/hyperspec-7.0/HyperSpec/"))
|
||
(t (message "Default Common Lisp HyperSpec access")))
|
||
|
||
(define-key sly-prefix-map (kbd "M-h") #'sly-documentation-lookup)))
|
||
#+end_src
|
||
|
||
#+caption[Script to dump a SBCL core for the Sly Common Lisp IDE]:
|
||
#+caption: Script to dump a SBCL core for the Sly Common Lisp IDE.
|
||
#+header: :tangle-mode (identity #o755)
|
||
#+name: lst:sbcl-core-for-sly
|
||
#+begin_src shell :noeval :tangle ~/bin/sbcl.core-for-sly
|
||
#!/bin/sh
|
||
|
||
sbcl <<EOF
|
||
(mapc 'require '(sb-bsd-sockets sb-posix sb-introspect sb-cltl2 asdf))
|
||
(save-lisp-and-die "sbcl.core-for-sly")
|
||
EOF
|
||
|
||
# Local Variables:
|
||
# mode: shell-script
|
||
# sh-indentation: 2
|
||
# sh-basic-offset: 2
|
||
# End:
|
||
#+end_src
|
||
|
||
*** [[https://courses.cs.northwestern.edu/325/][CS 325 AI Programming]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:cs-325-ai-programming
|
||
:END:
|
||
The [[https://courses.cs.northwestern.edu/325/][CS 325 AI Programming]] course allows to learn Common Lisp by self-study and
|
||
the page [[https://courses.cs.northwestern.edu/325/admin/lisp-setup.php][CS 325: Setting up Lisp]] gives instructions how to:
|
||
1. [[https://courses.cs.northwestern.edu/325/admin/lisp-setup.php#lisp][Download and install common lisp]].
|
||
2. [[https://courses.cs.northwestern.edu/325/admin/lisp-setup.php#quicklisp][Install Quicklisp]].
|
||
3. [[https://courses.cs.northwestern.edu/325/admin/lisp-setup.php#install-325][Install the CS325 library]].
|
||
|
||
*** [[https://www.quicklisp.org/][Quicklisp]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:quicklisp
|
||
:END:
|
||
[[https://www.quicklisp.org/][Quicklisp]] is a library manager for Common Lisp. Listing
|
||
[[lst:download+verify-quicklisp]] downloads the [[https://www.quicklisp.org/][Quicklisp]] file and verifies its
|
||
signature to prevent tampering. Listing [[lst:bootstrap-quicklisp]] tangles to a
|
||
shell script allowing to bootstrap [[https://www.quicklisp.org/][Quicklisp]] with [[http://www.sbcl.org/][SBCL]]. Listing
|
||
[[lst:quicklisp-sbclrc-file]] tangles to the a [[http://www.sbcl.org/][SBCL]] resource file with [[https://www.quicklisp.org/][Quicklisp]]
|
||
support.
|
||
|
||
#+caption[Download and verify =quicklisp=]:
|
||
#+caption: Download and verify =quicklisp=.
|
||
#+name: lst:download+verify-quicklisp
|
||
#+begin_src shell :dir ~ :results none :tangle no
|
||
curl -sS -O https://beta.quicklisp.org/quicklisp.lisp
|
||
curl -sS -O https://beta.quicklisp.org/quicklisp.lisp.asc
|
||
curl -sS -O https://beta.quicklisp.org/release-key.txt
|
||
gpg --import release-key.txt
|
||
gpg --verify quicklisp.lisp.asc quicklisp.lisp
|
||
#+end_src
|
||
|
||
#+caption[Bootstrap =quicklisp=]:
|
||
#+caption: Bootstrap =quicklisp=.
|
||
#+header: :tangle-mode (identity #o755)
|
||
#+name: lst:bootstrap-quicklisp
|
||
#+begin_src shell :noeval :tangle ~/bin/quicklisp-sbcl-bootstrap
|
||
#!/bin/sh
|
||
|
||
sbcl --load ~/quicklisp.lisp <<EOF
|
||
(quicklisp-quickstart:install)
|
||
(quit)
|
||
EOF
|
||
|
||
# Local Variables:
|
||
# mode: shell-script
|
||
# sh-indentation: 2
|
||
# sh-basic-offset: 2
|
||
# End:
|
||
#+end_src
|
||
|
||
#+caption[A =quicklisp= sbclrc file]:
|
||
#+caption: A =quicklisp= sbclrc file.
|
||
#+name: lst:quicklisp-sbclrc-file
|
||
#+begin_src lisp :tangle ~/.sbclrc
|
||
;;; Hey Emacs, this is my -*- lisp -*- .sbclrc file.
|
||
#-quicklisp
|
||
(let ((quicklisp-init (merge-pathnames "quicklisp/setup.lisp"
|
||
(user-homedir-pathname))))
|
||
(when (probe-file quicklisp-init)
|
||
(load quicklisp-init)))
|
||
#+end_src
|
||
|
||
** [[info:eintr#Top][Emacs Lisp Programming (info)]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:emacs-lisp-programming
|
||
:END:
|
||
|
||
1. [[https://www.masteringemacs.org/article/evaluating-elisp-emacs][Evaluating Elisp in Emacs]]
|
||
2. [[https://endlessparentheses.com/debugging-emacs-lisp-part-1-earn-your-independence.html][Debugging Elisp Part 1: Earn your independence]]
|
||
3. [[https://endlessparentheses.com/debugging-elisp-part-2-advanced-topics.html][Debugging Elisp Part 2: Advanced topics]]
|
||
4. [[http://xahlee.info/talk_show/xah_talk_show_2022-01-20.html][Xah talk show: Elisp coding: xah-add-space-after-comma]]
|
||
5. [[http://xahlee.info/talk_show/xah_talk_show_2022-01-22.html][Xah talk show: Elisp coding: narrow-to-region, sort-lines, hilight-unicode]]
|
||
|
||
** [[https://www.seas.upenn.edu/~chaoliu/2017/09/01/python-programming-in-emacs/][Python programming]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:python-programming
|
||
:END:
|
||
The [[https://www.emacswiki.org/emacs/PythonProgrammingInEmacs][Python Programming in Emacs]] wiki page lists options to enhance Emacs's
|
||
built-in ~python-mode~. Here, the focus is on two packages:
|
||
1. [[https://github.com/joaotavora/eglot][Eglot - Emacs polyGLOT: an Emacs LSP client that stays out of your way]]. The
|
||
maintainer also contributes to Emacs itself and has a deep understanding of
|
||
[[https://sheer.tj/the_way_of_emacs.html][the Way of Emacs]]. He refuses to add new features without seeing how they fit
|
||
into [[https://sheer.tj/the_way_of_emacs.html][the Way of Emacs]] as this discussion on [[https://github.com/joaotavora/eglot/issues/523][org-mode source code blocks]]
|
||
shows.
|
||
2. [[https://github.com/pythonic-emacs/anaconda-mode][Anaconda - code navigation, documentation lookup, and completion for Python]].
|
||
In my opinion, [[https://github.com/joaotavora/eglot][eglot]] has more potential than [[https://github.com/pythonic-emacs/anaconda-mode][anaconda]], but [[https://github.com/pythonic-emacs/anaconda-mode][anaconda]] is
|
||
compatible with [[info:org#Editing Source Code][source code block editing]] while [[https://github.com/joaotavora/eglot][eglot]] is not.
|
||
|
||
Here are a few links covering how to integrate Emacs, Python and a Python LSP
|
||
server, before plunging into the configuring steps:
|
||
1. [[https://taingram.org/blog/emacs-lsp-ide.html][Building Your Own Emacs IDE with LSP]]
|
||
2. [[https://rgoswami.me/posts/emacs-lang-servers/][Doom Emacs and Language Servers]]
|
||
3. [[https://ddavis.io/posts/eglot-python-ide/][Eglot based Emacs Python IDE]]
|
||
4. [[https://www.mattduck.com/lsp-python-getting-started.html][Getting started with lsp-mode for Python]]
|
||
5. [[https://ddavis.io/posts/python-emacs-3/][Python & Emacs, Take 3]]
|
||
6. [[https://ddavis.io/posts/emacs-python-lsp/][Python with Emacs: py(v)env and lsp-mode]]
|
||
|
||
*** [[https://git.savannah.gnu.org/cgit/emacs.git/tree/lisp/progmodes/python.el][Python-mode]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:python-mode
|
||
:END:
|
||
Listing [[lst:configure-python]] tells the Python shell to disregard its environment
|
||
variables (in particular =PYTHONSTARTUPFILE=). The [[https://github.com/pythonic-emacs/pythonic#readme][pythonic]] and [[https://github.com/jorgenschaefer/pyvenv#readme][pyvenv]] packages
|
||
provide support to handle Python virtual environments within Emacs. The [[https://github.com/pyenv/pyenv][pyenv]]
|
||
package provides support to work with [[https://github.com/pyenv/pyenv#readme][pyenv]] (eventually with [[https://github.com/pyenv/pyenv-virtualenv#readme][pyenv-virtualenv]])
|
||
to select between different python versions (eventually each with different
|
||
environments). In the end, all those packages do is to set
|
||
=python-shell-virtualenv-root= (in case of [[https://github.com/pyenv/pyenv#readme][pyenv]] and [[https://github.com/pythonic-emacs/pythonic#readme][pythonic]]) and tweak the
|
||
environment variables and restart the relevant Python child processes (in case
|
||
of [[https://github.com/jorgenschaefer/pyvenv#readme][pyvenv]]). Therefore, this setup replaces those packages with listing
|
||
[[lst:manage-pyenv]] to manage [[https://github.com/pyenv/pyenv#readme][pyenv]] from within Emacs and listing
|
||
[[lst:setting-python-shell-virtualenv-root]] to set
|
||
=python-shell-virtualenv-root=.
|
||
|
||
#+caption[Configure =python=]:
|
||
#+caption: Configure =python=.
|
||
#+name: lst:configure-python
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'python
|
||
(custom-set-variables
|
||
'(python-indent-guess-indent-offset nil)
|
||
'(python-shell-interpreter-args "-i -E")))
|
||
#+end_src
|
||
|
||
#+caption[Manage =pyenv=]:
|
||
#+caption: Manage =pyenv=.
|
||
#+name: lst:manage-pyenv
|
||
#+begin_src emacs-lisp
|
||
(when (executable-find "pyenv")
|
||
(defun pyenv-full-path (version)
|
||
"Return the full path for VERSION."
|
||
(unless (string= version "system")
|
||
(concat (pyenv-root) (file-name-as-directory "versions") version)))
|
||
|
||
(defun pyenv-root ()
|
||
"Return \"pyenv root\" as a directory."
|
||
(cl-destructuring-bind (exit-code output)
|
||
(shell-command-with-exit-code "pyenv" "root")
|
||
(if (= 0 exit-code) (file-name-as-directory (string-trim output))
|
||
(error "%s" (string-trim output)))))
|
||
|
||
(defun pyenv-version-name ()
|
||
"Return \"pyenv version-name\"."
|
||
(cl-destructuring-bind (exit-code output)
|
||
(shell-command-with-exit-code "pyenv" "version-name")
|
||
(if (= 0 exit-code) (string-trim output)
|
||
(error "%s" (string-trim output)))))
|
||
|
||
(defun pyenv-versions ()
|
||
"Return \"pyenv versions --bare --skip-aliases\" as a list.
|
||
Complete the result with \"system\"."
|
||
(cl-destructuring-bind (exit-code output)
|
||
(shell-command-with-exit-code
|
||
"pyenv" "versions" "--bare" "--skip-aliases")
|
||
(if (= 0 exit-code) (cons "system" (split-string output))
|
||
(error "%s" (string-trim output)))))
|
||
|
||
(defun pyenv-virtualenvs ()
|
||
"Return \"pyenv virtualenvs --bare --skip-aliases\" as a list."
|
||
(cl-destructuring-bind (exit-code output)
|
||
(shell-command-with-exit-code
|
||
"pyenv" "virtualenvs" "--bare" "--skip-aliases")
|
||
(if (= 0 exit-code) (split-string output)
|
||
(error "%s" (string-trim output))))))
|
||
#+end_src
|
||
|
||
#+caption[Setting =python-shell-virtualenv-root=]:
|
||
#+caption: Setting =python-shell-virtualenv-root=.
|
||
#+name: lst:setting-python-shell-virtualenv-root
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'python
|
||
(when (cl-every #'fboundp '(pyenv-full-path
|
||
pyenv-version-name
|
||
pyenv-versions
|
||
pyenv-virtualenvs))
|
||
(setq python-shell-virtualenv-root
|
||
(pyenv-full-path (or (car (pyenv-virtualenvs))
|
||
(car (pyenv-versions)))))
|
||
(message "Now `python-shell-virtualenv-root' equals \"%s\""
|
||
python-shell-virtualenv-root)
|
||
|
||
(defun set-python-shell-virtualenv-root-to-pyenv-version ()
|
||
"Set `python-shell-virtual-env-root' to a pyenv version."
|
||
(interactive)
|
||
(let* ((version-name (pyenv-version-name))
|
||
(prompt (format "pyenv version (%s): " version-name))
|
||
(choices (pyenv-versions))
|
||
(version (completing-read prompt choices nil 'require-match)))
|
||
(unless (string= version-name version)
|
||
(setq python-shell-virtualenv-root (pyenv-full-path version))
|
||
(setenv "PYENV_VERSION" version))
|
||
(message "Now `python-shell-virtualenv-root' equals \"%s\""
|
||
python-shell-virtualenv-root)))
|
||
|
||
(defun set-python-shell-virtualenv-root-to-pyenv-virtualenv ()
|
||
"Set `python-shell-virtual-env-root' to a pyenv virtualenv."
|
||
(interactive)
|
||
(let* ((version-name (pyenv-version-name))
|
||
(prompt (format "pyenv virtualenv (%s): " version-name))
|
||
(choices (pyenv-virtualenvs))
|
||
(version (completing-read prompt choices nil 'require-match)))
|
||
(unless (string= version-name version)
|
||
(setq python-shell-virtualenv-root (pyenv-full-path version))
|
||
(setenv "PYENV_VERSION" version))
|
||
(message "Now `python-shell-virtualenv-root' equals \"%s\""
|
||
python-shell-virtualenv-root)))))
|
||
#+end_src
|
||
|
||
*** [[https://github.com/joaotavora/eglot][Eglot]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:eglot
|
||
:END:
|
||
Listing [[lst:configure-eglot+python-lsp-server-for-python]] tangles to
|
||
=user-init-file= and configures [[https://github.com/joaotavora/eglot][eglot]] for [[https://www.python.org][Python]] using the [[https://github.com/python-lsp/python-lsp-server][python-lsp-server]].
|
||
In order to enable all builtin [[https://github.com/python-lsp/python-lsp-server][python-lsp-server]] capabilities, ensure
|
||
installation of the Python packages [[https://github.com/hhatto/autopep8#readme][autopep8]], [[https://github.com/PyCQA/flake8][flake8]], [[https://github.com/PyCQA/pydocstyle#readme][pydocstyle]], [[https://github.com/PyCQA/pylint#readme][pylint]], [[https://github.com/python-rope/rope#readme][rope]],
|
||
and [[https://github.com/google/yapf#readme][yapf]]. In addition, install the [[https://github.com/emanspeaks/pyls-flake8#readme][pyls-flake8]] plugin to let [[https://github.com/python-lsp/python-lsp-server][python-lsp-server]]
|
||
use [[https://github.com/PyCQA/flake8][flake8]].
|
||
|
||
Listing [[lst:on-hack-local-variables-hook-eglot-maybe]] defines a hook function to
|
||
launch [[https://github.com/joaotavora/eglot][eglot]] in presence of a proper [[info:emacs#Directory Variables][.dir-locals.el]] file in the root directory
|
||
of any [[https://www.python.org][Python]] project. Listing [[lst:eglot-directory-variables-for-python]] shows
|
||
such a proper [[info:emacs#Directory Variables][.dir-locals.el]] file.
|
||
|
||
#+caption[Configure =eglot= with =python-lsp-server= for Python]:
|
||
#+caption: Configure =eglot= with =python-lsp-server= for Python.
|
||
#+name: lst:configure-eglot+python-lsp-server-for-python
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'eglot
|
||
;; (setq eglot-server-programs '((python-mode "pylsp")))
|
||
(add-to-list 'eglot-server-programs '(python-mode "pylsp"))
|
||
|
||
(setq-default
|
||
eglot-workspace-configuration
|
||
'(;; Disable the `:pyls_flake8' plugin to fall back to pycodestyle.
|
||
(:pylsp . (:plugins (:pyls_flake8 (:enabled t))))
|
||
(:pylsp . (:plugins (:jedi_completion (:cache_for ["astropy"]))))
|
||
(:pylsp . (:plugins (:jedi (:auto_import_modules ["numpy"]))))))
|
||
|
||
(define-key eglot-mode-map (kbd "C-c n") #'flymake-goto-next-error)
|
||
(define-key eglot-mode-map (kbd "C-c p") #'flymake-goto-prev-error)
|
||
(define-key eglot-mode-map (kbd "C-c r") 'eglot-rename))
|
||
#+end_src
|
||
|
||
#+caption[Start =eglot= in case of a proper =dir-local-variables-alist=]:
|
||
#+caption: Start =eglot= in case of a proper =dir-local-variables-alist=.
|
||
#+name: lst:on-hack-local-variables-hook-eglot-maybe
|
||
#+begin_src emacs-lisp
|
||
(when (fboundp 'eglot-ensure)
|
||
;; The two hooks `after-change-major-mode-hook' and
|
||
;; `hack-local-variables-hook' are OK, but language mode hooks like
|
||
;; `python-mode-hook' are not.
|
||
(add-hook 'hack-local-variables-hook
|
||
(defun on-hack-local-variables-hook-eglot-maybe ()
|
||
(when (and (derived-mode-p 'python-mode)
|
||
(assoc 'eglot-workspace-configuration
|
||
dir-local-variables-alist))
|
||
(eglot-ensure)))))
|
||
#+end_src
|
||
|
||
#+caption[Propose =directory-variables= to launch =eglot=]:
|
||
#+caption: Propose =directory-variables= in the root of any Python project to
|
||
#+caption: launch =eglot=.
|
||
#+name: lst:eglot-directory-variables-for-python
|
||
#+begin_src emacs-lisp :tangle dir-locals.el
|
||
;; Proposal for a .dir-locals.el file in the root of any Python project.
|
||
((python-mode
|
||
. ((eglot-workspace-configuration
|
||
. (;; Disable the `:pyls_flake8' plugin to fall back to pycodestyle.
|
||
(:pylsp . (:plugins (:pyls_flake8 (:enabled t))))
|
||
(:pylsp . (:plugins (:jedi (:auto_import_modules ["numpy"]))))
|
||
(:pylsp . (:plugins (:jedi_completion (:cache_for ["astropy"])))))))))
|
||
#+end_src
|
||
|
||
#+attr_latex: :booktabs yes :float table
|
||
#+caption[Eglot related key bindings]:
|
||
#+caption: Eglot related key-bindings.
|
||
#+name: tab:eglot-related-key-bindings
|
||
|---------------------------+------------------+------------------|
|
||
| command | keys | key map |
|
||
|---------------------------+------------------+------------------|
|
||
| =xref-find-definition= | {{{kbd(M-.)}}} | =global-map= |
|
||
| =xref-pop= | {{{kbd(M-\,)}}} | =global-map= |
|
||
| =flymake-goto-next-error= | {{{kbd(C-c n)}}} | =eglot-mode-map= |
|
||
| =flymake-goto-prev-error= | {{{kbd(C-c p)}}} | =eglot-mode-map= |
|
||
| =eglot-rename= | {{{kbd(C-c r)}}} | =eglot-mode-map= |
|
||
| =eldoc-doc-buffer= | {{{kbd(C-h .)}}} | =eglot-mode-map= |
|
||
|---------------------------+------------------+------------------|
|
||
|
||
Listing [[lst:pyproject-toml-kick-off]] and [[lst:setup-cfg-kick-off]] implement the
|
||
rules in [[https://black.readthedocs.io/en/stable/guides/using_black_with_other_tools.html][using black with other tools]] in order to make [[https://flake8.pycqa.org/en/latest/][flake8]] or [[https://pycodestyle.pycqa.org/en/latest/][pycodestyle]]
|
||
agree with [[https://black.readthedocs.io/en/stable/index.html][black's uncompromising style]].
|
||
|
||
#+caption[Kick starting a =pyproject.toml= file]:
|
||
#+caption: Kick starting a =pyproject.toml= file.
|
||
#+name: lst:pyproject-toml-kick-off
|
||
#+begin_src toml :tangle pyproject.toml
|
||
[build-system]
|
||
requires = ["setuptools", "wheel"]
|
||
build-backend = "setuptools.build_meta"
|
||
|
||
[tool.black]
|
||
line-length = 88
|
||
#+end_src
|
||
|
||
#+caption[Kick starting a =setup.cfg= file]:
|
||
#+caption: Kick starting a =setup.cfg= file.
|
||
#+name: lst:setup-cfg-kick-off
|
||
#+begin_src toml :tangle setup.cfg
|
||
[flake8]
|
||
max-line-length = 88
|
||
extend-ignore = E203
|
||
|
||
[pycodestyle]
|
||
ignore = E203
|
||
max-line-length = 88
|
||
#+end_src
|
||
|
||
[[https://jedi.readthedocs.io/en/latest/][Jedi]] provides grammar checking and completion candidates to [[https://github.com/python-lsp/python-lsp-server][python-lsp-server]].
|
||
Only [[https://jedi.readthedocs.io/en/latest/docs/changelog.html][jedi-0.18.1]] works with for instance [[https://numpy.org/][numpy-1.22.0]] in the sense that it does
|
||
not choke on universal functions provided that [[https://jedi.readthedocs.io/en/latest/][jedi]] does not parse but imports
|
||
[[https://numpy.org/][numpy-1.22.0]] (see [[https://github.com/davidhalter/jedi/issues/1744][jedi issue #1744]], [[https://github.com/davidhalter/jedi/issues/1745][#1745]], and [[https://github.com/davidhalter/jedi/issues/1746][#1746]]). Since the universal
|
||
functions are neither builtin methods nor data instances but a kind of "callable
|
||
instances", the [[https://docs.python.org/3/library/inspect.html][Python inspect]] module also fails to handle the universal
|
||
functions properly.
|
||
|
||
Listing [[lst:make-pylsp-server-patch]] generates and listing
|
||
[[lst:echo-pylsp-server-patch]] echos the patch in listing
|
||
[[lst:show-pylsp-server-patch]] to make [[https://jedi.readthedocs.io/en/latest/][jedi]] import [[https://numpy.org/][numpy-1.22.2]] in order to serve
|
||
the information to [[https://github.com/python-lsp/python-lsp-server][python-lsp-server]] allowing it to handle universal functions.
|
||
|
||
#+caption[Make =pylsp-auto-import-modules.patch= listing]:
|
||
#+caption: Make =pylsp-auto-import-modules.patch= listing.
|
||
#+name: lst:make-pylsp-server-patch
|
||
#+begin_src shell :exports code :results none
|
||
git -C $HOME/VCS/python-lsp-server diff >pylsp-auto-import-modules.patch
|
||
#+end_src
|
||
|
||
#+caption[Echo =pylsp-auto-import-modules.patch= listing]:
|
||
#+caption: Echo =pylsp-auto-import-modules.patch= listing.
|
||
#+name: lst:echo-pylsp-server-patch
|
||
#+begin_src shell :exports both :results drawer
|
||
echo "#+attr_latex: :options breaklines"
|
||
echo "#+caption[Show =pylsp-auto-import-modules.patch=]:"
|
||
echo "#+caption: Show =pylsp-auto-import-modules.patch=."
|
||
echo "#+name: lst:show-pylsp-server-patch"
|
||
echo "#+begin_src diff :tangle no"
|
||
cat pylsp-auto-import-modules.patch
|
||
echo -n "#+end_src"
|
||
#+end_src
|
||
|
||
#+RESULTS: lst:echo-pylsp-server-patch
|
||
:results:
|
||
#+attr_latex: :options breaklines
|
||
#+caption[Show =pylsp-auto-import-modules.patch=]:
|
||
#+caption: Show =pylsp-auto-import-modules.patch=.
|
||
#+name: lst:show-pylsp-server-patch
|
||
#+begin_src diff :tangle no
|
||
diff --git a/pylsp/config/schema.json b/pylsp/config/schema.json
|
||
index d21027d..7ca0659 100644
|
||
--- a/pylsp/config/schema.json
|
||
+++ b/pylsp/config/schema.json
|
||
@@ -69,6 +69,14 @@
|
||
"default": null,
|
||
"description": "List of errors and warnings to enable."
|
||
},
|
||
+ "pylsp.plugins.jedi.auto_import_modules": {
|
||
+ "type": "array",
|
||
+ "default": ["numpy", "gi"],
|
||
+ "items": {
|
||
+ "type": "string"
|
||
+ },
|
||
+ "description": "List of module names for jedi to import (jedi.settings.auto_import_modules)."
|
||
+ },
|
||
"pylsp.plugins.jedi.extra_paths": {
|
||
"type": "array",
|
||
"default": [],
|
||
diff --git a/pylsp/workspace.py b/pylsp/workspace.py
|
||
index bf312f6..4758b53 100644
|
||
--- a/pylsp/workspace.py
|
||
+++ b/pylsp/workspace.py
|
||
@@ -14,6 +14,8 @@ from . import lsp, uris, _utils
|
||
|
||
log = logging.getLogger(__name__)
|
||
|
||
+DEFAULT_AUTO_IMPORT_MODULES = ["numpy", "gi"]
|
||
+
|
||
# TODO: this is not the best e.g. we capture numbers
|
||
RE_START_WORD = re.compile('[A-Za-z_0-9]*$')
|
||
RE_END_WORD = re.compile('^[A-Za-z_0-9]*')
|
||
@@ -252,6 +254,8 @@ class Document:
|
||
|
||
if self._config:
|
||
jedi_settings = self._config.plugin_settings('jedi', document_path=self.path)
|
||
+ jedi.settings.auto_import_modules = jedi_settings.get('auto_import_modules',
|
||
+ DEFAULT_AUTO_IMPORT_MODULES)
|
||
environment_path = jedi_settings.get('environment')
|
||
extra_paths = jedi_settings.get('extra_paths') or []
|
||
env_vars = jedi_settings.get('env_vars')
|
||
#+end_src
|
||
:end:
|
||
|
||
*** [[https://github.com/pythonic-emacs/blacken#readme][Blacken]] :noexport:
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:blacken
|
||
:header-args:emacs-lisp: :tangle no
|
||
:END:
|
||
Listing [[lst:configure-blacken]] configures [[https://github.com/pythonic-emacs/blacken#readme][blacken]] to format Python code with the
|
||
[[https://black.readthedocs.io/en/stable/index.html][Python Black code formatter]].
|
||
|
||
#+caption[Configure =blacken=]:
|
||
#+caption: Configure =blacken=.
|
||
#+name: lst:configure-blacken
|
||
#+begin_src emacs-lisp
|
||
(when (and (ensure-package-installation 'blacken)
|
||
(fboundp 'blacken-buffer))
|
||
(defun advice-derived-python-mode-p (fn &rest args)
|
||
(if (derived-mode-p 'python-mode)
|
||
(apply fn args)
|
||
(message "Refusal to run %S, since buffer is in %S." fn major-mode)))
|
||
|
||
(advice-add 'blacken-buffer :around #'advice-derived-python-mode-p))
|
||
#+end_src
|
||
|
||
*** [[https://jedi.readthedocs.io/en/latest/][Jedi]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:jedi
|
||
:END:
|
||
Listing [[lst:example-py]] is a [[https://www.python.org][Python]] example to test whether [[https://jedi.readthedocs.io/en/latest/][jedi]] in combination
|
||
with and either [[https://github.com/pythonic-emacs/anaconda-mode][anaconda]] or [[https://github.com/joaotavora/eglot][eglot]] works when coding certain functions of for
|
||
instance [[https://numpy.org/][numpy]] and [[https://scipy.org/][scipy]].
|
||
|
||
#+caption[Tangle the =example.py= file]:
|
||
#+caption: Tangle the =example.py= file.
|
||
#+name: lst:example-py
|
||
#+begin_src python :tangle example.py
|
||
import numpy
|
||
import astropy.units as apu
|
||
|
||
a = numpy.arange(0, 11)
|
||
a = numpy.linspace(0, 10, num=11)
|
||
a = numpy.arccos(a)
|
||
q = apu.Quantity(a, apu.meter)
|
||
print(q)
|
||
#+end_src
|
||
|
||
*** [[https://github.com/pythonic-emacs/anaconda-mode][Anaconda]] :noexport:
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:anaconda
|
||
:header-args:emacs-lisp: :tangle no
|
||
:END:
|
||
Listing [[lst:configure-anaconda+company-for-python]] and
|
||
[[lst:define-my-toggle-anaconda-mode]] configure [[https://github.com/pythonic-emacs/anaconda-mode][anaconda]]. See [[https://github.com/jorgenschaefer/elpy/blob/8d0de310d41ebf06b22321a8534546447456870c/elpy.el#L2775][elpy-module-company]]
|
||
for how to handle ~company-backends~ as a local variable in listing
|
||
[[lst:configure-anaconda+company-for-python]]. The call to [[info:elisp#Advising Functions][advice-add]] in listing
|
||
[[lst:define-my-toggle-anaconda-mode]] opens Python =org-edit-src-code= buffers in
|
||
~anaconda-mode~.
|
||
|
||
#+caption[Configure =anaconda= with =company= for Python]:
|
||
#+caption: Configure =anaconda= with =company= for Python.
|
||
#+name: lst:configure-anaconda+company-for-python
|
||
#+begin_src emacs-lisp
|
||
(when (ensure-package-installation 'anaconda-mode 'company-anaconda)
|
||
(with-eval-after-load 'python
|
||
(with-eval-after-load 'company
|
||
(when (and (fboundp 'anaconda-mode)
|
||
(fboundp 'company-anaconda))
|
||
(defun my-disable-anaconda-mode ()
|
||
(when (derived-mode-p 'python-mode)
|
||
(anaconda-mode -1)
|
||
(make-variable-buffer-local 'company-backends)
|
||
(setq company-backends
|
||
(delq 'company-anaconda
|
||
(mapcar #'identity company-backends)))
|
||
(anaconda-eldoc-mode -1)))
|
||
(defun my-enable-anaconda-mode ()
|
||
(when (derived-mode-p 'python-mode)
|
||
(anaconda-mode +1)
|
||
(make-variable-buffer-local 'company-backends)
|
||
(setq company-backends
|
||
(cons 'company-anaconda
|
||
(delq 'company-semantic
|
||
(delq 'company-capf
|
||
(mapcar #'identity company-backends)))))
|
||
(anaconda-eldoc-mode
|
||
(if (file-remote-p default-directory) -1 1))))))))
|
||
#+end_src
|
||
|
||
#+caption[Define =my-toggle-anaconda-mode= for Python]:
|
||
#+caption: Define =my-toggle-anaconda-mode= for Python.
|
||
#+name: lst:define-my-toggle-anaconda-mode
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'python
|
||
(unless (and (fboundp 'my-disable-anaconda-mode)
|
||
(fboundp 'my-enable-anaconda-mode))
|
||
(when (fboundp 'anaconda-mode)
|
||
(defun my-disable-anaconda-mode ()
|
||
(when (derived-mode-p 'python-mode)
|
||
(anaconda-mode -1)
|
||
(anaconda-eldoc-mode -1)))
|
||
(defun my-enable-anaconda-mode ()
|
||
(when (derived-mode-p 'python-mode)
|
||
(anaconda-mode +1)
|
||
(anaconda-eldoc-mode
|
||
(if (file-remote-p default-directory) -1 1))))))
|
||
|
||
(when (fboundp 'my-enable-anaconda-mode)
|
||
(advice-add 'org-edit-src-code :after #'my-enable-anaconda-mode))
|
||
(when (and (fboundp 'my-disable-anaconda-mode)
|
||
(fboundp 'my-enable-anaconda-mode))
|
||
(defun my-toggle-anaconda-mode ()
|
||
"Toggle anaconda-mode with bells and whistles."
|
||
(interactive)
|
||
(if (bound-and-true-p anaconda-mode)
|
||
(my-disable-anaconda-mode)
|
||
(my-enable-anaconda-mode)))))
|
||
#+end_src
|
||
|
||
*** [[https://github.com/astoff/code-cells.el#readme][Code-cells]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:code-cells
|
||
:END:
|
||
|
||
[[https://github.com/astoff/code-cells.el#readme][Code-cells]] allows to edit [[https://ipython.org/notebook.html][IPython or Jupyter notebooks]] in Emacs with help from
|
||
either [[https://github.com/mwouts/jupytext][Jupytext]] or [[https://pandoc.org/][Pandoc]] to translate between the [[https://nbformat.readthedocs.io/en/latest/][ipynb]] format and different
|
||
plain text formats. Sofar, I have used [[https://github.com/astoff/code-cells.el#readme][code-cells]] to open [[https://nbformat.readthedocs.io/en/latest/][ipynb]] notebooks with
|
||
{{{kbd(C-x C-f)}}} in Emacs for viewing. Listing [[lst:configure-code-cells]]
|
||
configures =code-cells=.
|
||
|
||
#+caption[Configure =code-cells=]:
|
||
#+caption: Configure =code-cells=.
|
||
#+name: lst:configure-code-cells
|
||
#+begin_src emacs-lisp
|
||
(when (ensure-package-installation 'code-cells)
|
||
(with-eval-after-load 'code-cells
|
||
(let ((map code-cells-mode-map))
|
||
(define-key map (kbd "M-p") #'code-cells-backward-cell)
|
||
(define-key map (kbd "M-n") #'code-cells-forward-cell)
|
||
(define-key map (kbd "C-c C-c") #'code-cells-eval))))
|
||
#+end_src
|
||
|
||
*** TODO Look into: editing facilities
|
||
1. [[https://github.com/douglasdavis/numpydoc.el/blob/main/numpydoc.el][Emacs extension to insert numpy style docstrings in function definitions]]
|
||
|
||
* [[https://github.com/emacs-tw/awesome-emacs#library][Libraries]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:libraries
|
||
:END:
|
||
** [[info:dash.info#Top][Library dash.el (info)]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:dash-library
|
||
:END:
|
||
The library [[info:dash.info#Top][dash.el (info)]]positions itself as a modern alternative for the list
|
||
processing API of [[info:cl#Top][cl]]. It is a requirement of several important packages in this
|
||
Emacs setup (for instance [[https://github.com/andras-simonyi/citeproc-el#readme][citeproc]], [[https://github.com/magit/magit#readme][magit]], and [[https://github.com/Fuco1/smartparens#readme][smartparens]]). Listing
|
||
[[lst:configure-dash]] enables fontification of =dash= macros and makes
|
||
=info-lookup-symbol= take into account the =dash= macros.
|
||
|
||
#+caption[Configure =dash= fontification and info lookup]:
|
||
#+caption: Configure =dash= fontification and info lookup.
|
||
#+name: lst:configure-dash
|
||
#+begin_src emacs-lisp
|
||
(when (fboundp #'global-dash-fontify-mode)
|
||
(global-dash-fontify-mode))
|
||
|
||
(when (fboundp #'dash-register-info-lookup)
|
||
(with-eval-after-load 'info-look
|
||
(dash-register-info-lookup)))
|
||
#+end_src
|
||
|
||
** [[https://github.com/rejeep/f.el][Library f.el]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:f-library
|
||
:END:
|
||
The library [[https://github.com/rejeep/f.el][f.el]] positions itself as a modern API for working with files and
|
||
directories in Emacs. It is a requirement of the [[https://github.com/andras-simonyi/citeproc-el#readme][citeproc]] package in this Emacs
|
||
setup and requires no configuration.
|
||
|
||
** [[https://github.com/magnars/s.el][Library s.el]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:s-library
|
||
:END:
|
||
The library [[https://github.com/magnars/s.el][s.el]] positions itself as the long lost Emacs string manipulation
|
||
library. It is a requirement of the [[https://github.com/andras-simonyi/citeproc-el#readme][citeproc]] and [[https://github.com/bdarcus/citar#readme][citar]] packages in this Emacs
|
||
setup and requires no configuration.
|
||
|
||
* [[info:emacs#Minor Modes][Minor Modes (info)]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:minor-modes
|
||
:END:
|
||
|
||
** [[https://github.com/victorhge/iedit#readme][Synchronal multiple-region editing]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:synchronal-multiple-region-editing
|
||
:END:
|
||
|
||
#+caption[Enable =iedit=]:
|
||
#+caption: Enable =iedit=.
|
||
#+name: lst:enable-iedit
|
||
#+begin_src emacs-lisp
|
||
(when (ensure-package-installation 'iedit)
|
||
(require 'iedit nil 'noedit))
|
||
#+end_src
|
||
|
||
** [[https://github.com/lewang/ws-butler#readme][Unobtrusive whitespace trimming]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:unobtrusive-whitespace-trimming
|
||
:END:
|
||
|
||
#+caption[Configure =ws-butler=]:
|
||
#+caption: Configure =ws-butler=.
|
||
#+name: lst:configure-ws-butler
|
||
#+begin_src emacs-lisp
|
||
(when (and (ensure-package-installation 'ws-butler)
|
||
(require 'ws-butler nil 'noerror))
|
||
(custom-set-variables
|
||
'(ws-butler-keep-whitespace-before-point nil))
|
||
(add-hook 'prog-mode-hook #'ws-butler-mode)
|
||
(add-hook 'text-mode-hook #'ws-butler-mode))
|
||
#+end_src
|
||
|
||
** [[https://countvajhula.com/2021/09/25/the-animated-guide-to-symex/][Structural editing]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:structural-editing
|
||
:END:
|
||
|
||
Structural editing keeps character pairs (for instance parentheses, curly and
|
||
square brackets as well as single and double quotes) balanced to leave code (for
|
||
instance Lisp and Python) and text (for instance LaTeX and Org) structure
|
||
intact. I use [[https://github.com/Fuco1/smartparens][smartparens]] which offers a normal mode (=smartparens-mode=) and a
|
||
a strict mode (=smartparens-strict-mode=). Although both modes insert character
|
||
pairs, the normal mode allows to delete one of the paired characters easily
|
||
while the strict mode does not. Therefore, the strict mode is more for code
|
||
editing since it never breaks programming language rules and the normal mode is
|
||
more for text editing where structure is a matter of convention instead of
|
||
programming language rules.
|
||
|
||
For instance, the strict mode in Python allows to delete entire lists, tuples,
|
||
or the arguments after the cursor (what Emacs calls =point=) in a function call
|
||
without breaking the character pair balance. In order to repair a broken
|
||
character pair balance, insert a single character by prefixing it with "C-q"
|
||
bound to =quoted-insert=.
|
||
|
||
The [[https://smartparens.readthedocs.io/en/latest/index.html][smartparens documentation]] targets experienced Emacs users. The
|
||
following links show how to put the documentation to practical use:
|
||
1. [[https://gist.github.com/oantolin][Omar Antolin's gist "my-smartparens-config.el"]] is the first place to look for
|
||
how to tweak [[https://github.com/Fuco1/smartparens][smartparens]]. However, the gist may be partially obsolete, since
|
||
it is not part of his current [[https://github.com/oantolin/emacs-config][Emacs configuration]].
|
||
2. [[https://lists.gnu.org/archive/html/help-gnu-emacs/2014-07/msg00135.html][How to enable smartparens in the minibuffer after eval-expression]] explains
|
||
how the machinery after the first and after later usages of =eval-expression=
|
||
differ and discusses options how to handle those differences.
|
||
Listing [[lst:configure-smartparens]] aims to configure [[https://github.com/Fuco1/smartparens][smartparens]] for Elisp,
|
||
LaTeX, Org, and Python.
|
||
|
||
Despite the provocative post [[https://andreyorst.gitlab.io/posts/2022-02-20-what-if-structural-editing-was-a-mistake/]["What if structural editing was a mistake?"]],
|
||
[[https://github.com/Fuco1/smartparens][smartparens]] is one of my favorite packages. In particular, [[https://github.com/Fuco1/smartparens][smartparens]] handles
|
||
matching pairs in Org-mode files with export and source blocks for multiple
|
||
formats and languages correctly. Therefore, [[https://smartparens.readthedocs.io/en/latest/index.html?highlight=show-smartparens-mode#getting-started][show-smartparens-mode]] highlights
|
||
matching pairs immediately in front or after point in such files correctly,
|
||
contrary to for instance [[https://github.com/Fanael/rainbow-delimiters#readme][rainbow-delimiters]].
|
||
|
||
#+caption[Configure =smartparens=]:
|
||
#+caption: Configure =smartparens=.
|
||
#+name: lst:configure-smartparens
|
||
#+begin_src emacs-lisp
|
||
(when (and (ensure-package-installation 'smartparens)
|
||
;; Require `smartparens-config' instead of `smartparens' to
|
||
;; disable pairing of the quote character for lisp modes.
|
||
(require 'smartparens-config nil 'noerror))
|
||
(custom-set-variables
|
||
'(sp-base-key-bindings 'sp)
|
||
'(sp-override-key-bindings '(("C-(" . sp-backward-barf-sexp)
|
||
("C-)" . sp-forward-slurp-sexp))))
|
||
|
||
(dolist (hook '(prog-mode-hook text-mode-hook))
|
||
(add-hook hook #'smartparens-mode))
|
||
|
||
(dolist (hook '(emacs-lisp-mode-hook
|
||
ielm-mode-hook
|
||
lisp-mode-hook
|
||
python-mode-hook
|
||
sly-mrepl-mode-hook))
|
||
(add-hook hook #'smartparens-strict-mode))
|
||
|
||
;; https://xenodium.com/emacs-smartparens-auto-indent/index.html
|
||
(defun indent-between-pair (&rest _ignored)
|
||
(newline)
|
||
(indent-according-to-mode)
|
||
(forward-line -1)
|
||
(indent-according-to-mode))
|
||
|
||
(dolist (left '("(" "[" "{"))
|
||
(sp-local-pair 'prog-mode left
|
||
nil :post-handlers '((indent-between-pair "RET"))))
|
||
|
||
(show-smartparens-global-mode +1))
|
||
#+end_src
|
||
|
||
** [[https://github.com/davidshepherd7/electric-operator#readme][Electric operators]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:electric-operators
|
||
:END:
|
||
|
||
Listing [[lst:configure-electric-operator]] configures =electric-operator-mode=
|
||
to add spaces around operators for compatibility with for instance the [[https://black.readthedocs.io/en/stable/][Black
|
||
code formatter for Python]].
|
||
|
||
#+caption[Configure =electric-operator=]:
|
||
#+caption: Configure =electric-operator=.
|
||
#+name: lst:configure-electric-operator
|
||
#+begin_src emacs-lisp
|
||
(when (and (ensure-package-installation 'electric-operator)
|
||
(fboundp 'electric-operator-mode))
|
||
(add-hook 'c-mode-common #'electric-operator-mode)
|
||
(add-hook 'python-mode-hook #'electric-operator-mode))
|
||
#+end_src
|
||
|
||
** [[https://joaotavora.github.io/yasnippet/][Smart snippets]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:smart-snippets
|
||
:END:
|
||
|
||
#+caption[Enable =yas-global-mode=]:
|
||
#+caption: Enable =yas-global-mode=.
|
||
#+name: lst:enable-yas-global-mode
|
||
#+begin_src emacs-lisp
|
||
(when (and (ensure-package-installation 'yasnippet)
|
||
(require 'yasnippet nil 'noerror))
|
||
(custom-set-variables
|
||
'(yas-alias-to-yas/prefix-p nil))
|
||
(yas-global-mode +1))
|
||
#+end_src
|
||
|
||
* [[info:emacs#Display][Display (info)]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:display
|
||
:END:
|
||
|
||
** [[info:emacs#Narrowing][Narrowing]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:narrowing
|
||
:END:
|
||
|
||
Narrowing means focusing in on some portion of the buffer and widening means
|
||
focussing out on the whole buffer. This allows to concentrate temporarily on
|
||
for instance a particular function or paragraph by removing clutter. The "Do
|
||
What I Mean" [[https://endlessparentheses.com/emacs-narrow-or-widen-dwim.html][narrow-or-widen-dwim]] function allows to toggle between narrowed and
|
||
widened buffer states. Here, the function =narrow-or-widen-dwim= operates also
|
||
on tables by means of =org-narrow-to-table=.
|
||
|
||
#+caption[Configure =narrow-or-widen-dwim=]:
|
||
#+caption: Configure =narrow-or-widen-dwim=.
|
||
#+name: lst:configure-narrow-or-widen-dwim
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'emacs
|
||
(autoload 'org-at-table "org-table")
|
||
|
||
(defun org-narrow-to-table ()
|
||
"Narrow buffer to current table."
|
||
(interactive)
|
||
(if (org-at-table-p)
|
||
(narrow-to-region (org-table-begin) (org-table-end))
|
||
(user-error "Not in a table")))
|
||
|
||
(defun narrow-or-widen-dwim (p)
|
||
"Widen if buffer is narrowed, narrow-dwim otherwise.
|
||
Dwim means: region, org-src-block, org-table, org-subtree, LaTeX
|
||
environment, TeX group, or defun, whichever applies first.
|
||
Narrowing to org-src-block actually calls `org-edit-src-code'.
|
||
With prefix P, don't widen, just narrow even if buffer is already
|
||
narrowed."
|
||
(interactive "P")
|
||
(declare (interactive-only))
|
||
(cond ((and (buffer-narrowed-p) (not p)) (widen))
|
||
((and (bound-and-true-p org-src-mode) (not p))
|
||
(org-edit-src-exit))
|
||
((region-active-p)
|
||
(narrow-to-region (region-beginning) (region-end)))
|
||
((derived-mode-p 'org-mode)
|
||
(or (ignore-errors (org-edit-src-code))
|
||
(ignore-errors (org-narrow-to-block))
|
||
(ignore-errors (org-narrow-to-table))
|
||
(org-narrow-to-subtree)))
|
||
((derived-mode-p 'latex-mode)
|
||
(LaTeX-narrow-to-environment))
|
||
((derived-mode-p 'tex-mode)
|
||
(TeX-narrow-to-group))
|
||
(t (narrow-to-defun))))
|
||
|
||
(define-key ctl-x-map (kbd "n t") #'org-narrow-to-table)
|
||
(define-key ctl-x-map (kbd "C-n") #'narrow-or-widen-dwim))
|
||
#+end_src
|
||
|
||
** [[info:emacs#Faces][Text faces or styles (info)]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:text-faces-or-styles
|
||
:END:
|
||
|
||
This setup does not configure [[info:emacs#Custom Themes][custom themes (info)]] in order to prevent endless
|
||
useless tweaking. See the [[https://protesilaos.com/codelog/2020-09-05-emacs-note-mixed-font-heights/][note on mixed font heights in Emacs]] for how to setup
|
||
fonts properly. It boils down to two rules:
|
||
1. The height of the default face must be an integer number to make the height a
|
||
physical quantity.
|
||
2. The heights of all other faces must be real numbers to scale those heights
|
||
with respect to the height of the face (those heights default to 1.0 for no
|
||
scaling).
|
||
The code in listing [[lst:configure-face-attributes]] source implements those rules.
|
||
In case of proper initialization of all face heigths, font scaling is easy as
|
||
listing [[lst:set-default-face-height]] shows.
|
||
|
||
#+caption[Configure =face-attributse=]:
|
||
#+caption: Configure =face-attributes=.
|
||
#+name: lst:configure-face-attributes
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'emacs
|
||
;; Set face attributes.
|
||
(cond
|
||
((eq system-type 'darwin)
|
||
(set-face-attribute 'default nil :family "Hack" :height 120)
|
||
(set-face-attribute 'fixed-pitch nil :family "Hack")
|
||
(set-face-attribute 'variable-pitch nil :family "FiraGo"))
|
||
((eq system-type 'gnu/linux)
|
||
(set-face-attribute 'default nil :family "Hack" :height 110)
|
||
(set-face-attribute 'fixed-pitch nil :family "Hack")
|
||
(set-face-attribute 'variable-pitch nil :family "FiraGo"))
|
||
(t
|
||
(set-face-attribute 'default nil :family "Hack" :height 110)
|
||
(set-face-attribute 'fixed-pitch nil :family "Hack")
|
||
(set-face-attribute 'variable-pitch nil :family "DejaVu Sans"))))
|
||
#+end_src
|
||
|
||
#+caption[Implement =set-default-face-height=]:
|
||
#+caption: Implement =set-default-face-height=.
|
||
#+name: lst:set-default-face-height
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'emacs
|
||
(defun set-default-face-height ()
|
||
"Set the default face height in all current and future frames.
|
||
|
||
Scale all other faces with a height that is a real number."
|
||
(interactive)
|
||
(let* ((prompt (format "face heigth (%s): "
|
||
(face-attribute 'default :height)))
|
||
(choices (mapcar #'number-to-string
|
||
(number-sequence 50 200 10)))
|
||
(height (string-to-number
|
||
(completing-read prompt choices nil 'require-match))))
|
||
(message "Setting the height of the default face to %s" height)
|
||
(set-face-attribute 'default nil :height height))))
|
||
#+end_src
|
||
|
||
** [[https://jblevins.org/log/rainbow-mode][Visualize color codes and names]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:rainbow-mode
|
||
:END:
|
||
|
||
Listing [[lst:enable-rainbow-mode]] enables =rainbow-mode= to colorize color codes
|
||
and names in buffers for debugging.
|
||
|
||
#+caption[Enable =rainbow-mode=]:
|
||
#+caption: Enable =rainbow-mode=.
|
||
#+name: lst:enable-rainbow-mode
|
||
#+begin_src emacs-lisp
|
||
(when (and (ensure-package-installation 'rainbow-mode)
|
||
(fboundp 'rainbow-mode))
|
||
(custom-set-variables
|
||
'(rainbow-x-colors-major-mode-list
|
||
'(c++-mode
|
||
c-mode
|
||
emacs-lisp-mode
|
||
inferior-emacs-lisp-mode
|
||
java-mode
|
||
lisp-interaction-mode
|
||
org-mode
|
||
python-mode)))
|
||
(rainbow-mode +1))
|
||
#+end_src
|
||
|
||
** [[https://karthinks.com/software/batteries-included-with-emacs/][Flash the line around point for visual feedback]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:flash-line-around-point
|
||
:END:
|
||
|
||
Listing [[lst:flash-line-around-point]] implements flashing of the line around point
|
||
for visual feedback after a selection of commands that make it hard to track
|
||
point movements visually.
|
||
|
||
#+caption[Implement =flash-line-around-point=]:
|
||
#+caption: Implement =flash-line-around-point=.
|
||
#+name: lst:flash-line-around-point
|
||
#+begin_src emacs-lisp
|
||
;; Ensure loading `pulse' with the dynamic variables `pulse-delay' and
|
||
;; `pulse-iterations' before masking them lexically instead of after
|
||
;; to prevent the warning triggered by lazy loading.
|
||
(when (require 'pulse nil 'noerror)
|
||
;; https://karthinks.com/software/batteries-included-with-emacs/
|
||
;; https://www.reddit.com/r/emacs/comments/jwhr6g/batteries_included_with_emacs/
|
||
(defun flash-line-around-point (&rest _)
|
||
"Flash the line around point."
|
||
(let ((pulse-iterations 16)
|
||
(pulse-delay 0.1))
|
||
(pulse-momentary-highlight-one-line (point))))
|
||
|
||
(dolist (command '(scroll-up-command
|
||
scroll-down-command
|
||
recenter-top-bottom
|
||
other-window))
|
||
(advice-add command :after #'flash-line-around-point)))
|
||
#+end_src
|
||
|
||
* Applications
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:applications
|
||
:END:
|
||
|
||
** [[info:emacs#Hyperlinking][Hyperlinking and Web Navigation Features (info)]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:hyperlinking-web-navigating
|
||
:END:
|
||
|
||
*** [[info:emacs#Browse-URL][Browse URL (info)]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:browse-url
|
||
:END:
|
||
|
||
Listing [[lst:configure-browse-url]] configures =browse-url=.
|
||
|
||
#+attr_latex: :options breaklines
|
||
#+caption[Configure =browse-url=]:
|
||
#+caption: Configure =browse-url=.
|
||
#+name: lst:configure-browse-url
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'browse-url
|
||
(defun browse-url-mpv (url &optional _)
|
||
(start-process "mpv" nil "mpv" url))
|
||
|
||
(defconst browse-url-mpv-regexp
|
||
(rx bos
|
||
(or "http://" "https://")
|
||
(or (or "www.youtube.com/" "youtu.be/" "soundcloud.com/")
|
||
(seq (+? nonl) (or ".mp4" ".webm") eos)))
|
||
"Match hyperlinks to browse with mpv.")
|
||
|
||
(if (version< emacs-version "28.0")
|
||
(custom-set-variables
|
||
'(browse-url-browser-function
|
||
`((,browse-url-mpv-regexp . browse-url-mpv)
|
||
("." . eww-browse-url))))
|
||
(custom-set-variables
|
||
'(browse-url-handlers
|
||
`((,browse-url-mpv-regexp . browse-url-mpv)
|
||
("." . eww-browse-url)))))
|
||
|
||
(custom-set-variables
|
||
`(browse-url-generic-program ,(or (when (eq system-type 'darwin) "open")
|
||
(executable-find "firefox")))))
|
||
#+end_src
|
||
|
||
*** [[https://en.wikipedia.org/wiki/Eww_(web_browser)][Emacs Web Wowser]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:emacs-web-wowser
|
||
:END:
|
||
|
||
#+caption[Configure =eww= URLs]:
|
||
#+caption: Configure =eww= URLs.
|
||
#+name: lst:configure-eww-urls
|
||
#+begin_src emacs-lisp
|
||
(when (fboundp 'eww-browse-url)
|
||
(defun eww-subreddit ()
|
||
"Read a subreddit in Emacs."
|
||
(interactive)
|
||
(eww-browse-url (format "www.reddit.com/r/%s/.mobile"
|
||
(completing-read "subreddit: "
|
||
'("emacs"
|
||
"i3wm"
|
||
"orgmode")
|
||
nil t)))))
|
||
#+end_src
|
||
|
||
#+caption[Configure =eww= rendering]:
|
||
#+caption: Configure =eww= rendering.
|
||
#+name: lst:configure-eww-rendering
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'eww
|
||
(defun eww-rename-buffer ()
|
||
"Rename the buffer using title or url."
|
||
(let* ((title (plist-get eww-data :title))
|
||
(name (or (and (eq "" title) (plist-get eww-data :url)) title)))
|
||
(rename-buffer (format "*%s # eww*" name) t)))
|
||
|
||
(add-hook 'eww-after-render-hook #'eww-rename-buffer))
|
||
#+end_src
|
||
|
||
*** [[https://en.wikipedia.org/wiki/Media_type#Mailcap][Mailcap]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:mailcap
|
||
:END:
|
||
|
||
Extension packages as [[info:emacs#EWW][EWW (info)]], [[info:emacs#Gnus][Gnus (info)]], and [[info:org#Top][Org (info)]] rely on a [[https://en.wikipedia.org/wiki/Media_type#Mailcap][mailcap]]
|
||
file to know what application should open a specific media file type. Listing
|
||
[[lst:tangle-mailcap-file]] specifies =emacsclient= as the application to open PDF
|
||
files.
|
||
|
||
#+caption[Tangle =mailcap= file]:
|
||
#+caption: Tangle =mailcap= file.
|
||
#+name: lst:tangle-mailcap-file
|
||
#+begin_src org :tangle ~/.mailcap
|
||
# https://emacs.stackexchange.com/a/24502 answers the question:
|
||
# How to use pdf-tools (pdf-view-mode) in emacs?
|
||
application/pdf; emacsclient %s
|
||
#+end_src
|
||
|
||
*** [[https://www.emacswiki.org/emacs/WebJump][Webjump]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:webjump
|
||
:END:
|
||
|
||
Listing [[lst:configure-webjump]] binds {{{kbd(C-c j)}}} to =webjump= and
|
||
initializes a list of =webjump-sites=.
|
||
|
||
#+attr_latex: :options breaklines
|
||
#+caption[Configure =webjump=]:
|
||
#+caption: Configure =webjump=.
|
||
#+name: lst:configure-webjump
|
||
#+begin_src emacs-lisp
|
||
(when (fboundp 'webjump)
|
||
(global-set-key (kbd "C-c j") 'webjump)
|
||
(with-eval-after-load 'webjump
|
||
(custom-set-variables
|
||
'(webjump-sites
|
||
'(("CS 325 AI Programming" . "courses.cs.northwestern.edu/325")
|
||
("Emacs Git Repository" . "git.savannah.gnu.org/cgit/emacs.git")
|
||
("Emacs News" . "sachachua.com/blog/category/emacs-news")
|
||
("GNU ELPA Git Repository" . "git.savannah.gnu.org/cgit/emacs/elpa.git")
|
||
("NonGNU ELPA Git Repository" . "git.savannah.gnu.org/cgit/emacs/nongnu.git")
|
||
("Org Mode Git Repository" . "git.savannah.gnu.org/cgit/emacs/org-mode.git")
|
||
("Org Mode List" . "list.orgmode.org")
|
||
("Worg - Org Mode Community" . "orgmode.org/worg")
|
||
("Planet Emacs Life" . "planet.emacslife.com")
|
||
("Asian Pacific Journal Japan Focus" . "apjjf.org")
|
||
("Counterpunch" . "www.counterpunch.org")
|
||
("Dictionary EN" . [simple-query "thefreedictionary.com"
|
||
"thefreedictionary.com/" ""])
|
||
;; CNTRL refuses http, accepts https, and lets Eww hang.
|
||
;; ("Dictionary FR" . [simple-query "www.cntrl.fr"
|
||
;; "https://www.cntrl.fr/definition/" ""])
|
||
("Dictionary NL" . [simple-query "www.woorden.org"
|
||
"www.woorden.org/woord/" ""])
|
||
("Dictionary Webster" . [simple-query
|
||
"www.webster-dictionary.org"
|
||
"www.webster-dictionary.org/definition/" ""])
|
||
("NRC". "www.nrc.nl")
|
||
("The Guardian" . "www.theguardian.com/international")
|
||
("Trouw" . "www.trouw.nl")
|
||
("Volkskrant" . "www.volkskrant.nl"))))))
|
||
#+end_src
|
||
|
||
** [[https://github.com/skeeto/elfeed#readme][Elfeed: Emacs web feed reader]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:emacs-web-feed-reader
|
||
:END:
|
||
|
||
Listing [[lst:configure-elfeed]] configures =elfeed= and makes a minimal attempt to
|
||
enable =emms=.
|
||
|
||
#+attr_latex: :options breaklines
|
||
#+caption[Configure =elfeed=]:
|
||
#+caption: Configure =elfeed=.
|
||
#+name: lst:configure-elfeed
|
||
#+begin_src emacs-lisp
|
||
(when (and (ensure-package-installation 'elfeed)
|
||
(fboundp 'elfeed))
|
||
(global-set-key (kbd "C-x w") #'elfeed)
|
||
|
||
(with-eval-after-load 'elfeed
|
||
(custom-set-variables
|
||
'(elfeed-feeds
|
||
'(("http://www.howardism.org/index.xml" h-abrams)
|
||
("https://emacshorrors.com/feed.atom" v-schneidermann)
|
||
("https://emacsninja.com/emacs.atom" v-schneidermann)
|
||
("https://feeds.feedburner.com/InterceptedWithJeremyScahill" j-scahill)
|
||
("https://nullprogram.com/feed/" c-wellons)
|
||
("https://oremacs.com/atom.xml" o-krehel)
|
||
("https://planet.emacslife.com/atom.xml" planet-emacs)
|
||
("https://protesilaos.com/codelog.xml" p-stavrou)
|
||
("https://sachachua.com/blog/category/emacs/feed" s-chua)
|
||
("https://sciencescitoyennes.org/feed/" sciences)
|
||
("https://updates.orgmode.org/feed/updates" org-updates)
|
||
("https://www.bof.nl/rss/" bof)
|
||
("https://www.democracynow.org/podcast-video.xml" dn)
|
||
("https://www.laquadrature.net/fr/rss.xml" lqdn)
|
||
("https://www.lemonde.fr/blog/huet/feed/" sciences)))))
|
||
|
||
(with-eval-after-load 'elfeed-show
|
||
(when (require 'emms-setup nil 'noerror)
|
||
(emms-all))))
|
||
#+end_src
|
||
|
||
** [[info:emms#Top][Emacs Multimedia System (info)]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:emacs-multimedia-system
|
||
:END:
|
||
|
||
The link [[https://sqrtminusone.xyz/posts/2021-09-07-emms/][my emms and elfeed setup]] is a nice introduction to configuring and
|
||
using =emms= with =elfeed=. Listing [[lst:configure-emms]] configures =emms=.
|
||
|
||
#+caption[Configure =emms=]:
|
||
#+caption: Configure =emms=.
|
||
#+name: lst:configure-emms
|
||
#+begin_src emacs-lisp
|
||
(when (ensure-package-installation 'emms)
|
||
(with-eval-after-load 'emms
|
||
(custom-set-variables
|
||
'(emms-player-list '(emms-player-mpd emms-player-mpv))))
|
||
|
||
(with-eval-after-load 'emms-mode-line
|
||
(custom-set-variables
|
||
'(emms-mode-line-format "")))
|
||
|
||
(with-eval-after-load 'emms-player-mpd
|
||
(custom-set-variables
|
||
`(emms-player-mpd-music-directory ,(expand-file-name "~/Music"))
|
||
'(emms-player-mpd-server-name "localhost")
|
||
'(emms-player-mpd-server-port "6600")
|
||
'(emms-player-mpd-verbose t)))
|
||
|
||
(with-eval-after-load 'emms-player-mpv
|
||
(custom-set-variables
|
||
'(emms-player-mpv-ipc-method 'ipc-server)
|
||
'(emms-player-mpv-update-metadata t)))
|
||
|
||
(with-eval-after-load 'emms-playing-time
|
||
(custom-set-variables
|
||
'(emms-playing-time-display-format " %s ")))
|
||
|
||
(with-eval-after-load 'emms-playlist-mode
|
||
(custom-set-variables
|
||
'(emms-playlist-mode-center-when-go t)))
|
||
|
||
(with-eval-after-load 'emms-streams
|
||
(custom-set-variables
|
||
`(emms-streams-file
|
||
,(no-littering-expand-etc-file-name "emms/streams.emms")))
|
||
(emms-all)))
|
||
#+end_src
|
||
|
||
*** Taming spurious buffers
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:taming-spurious-buffers
|
||
:END:
|
||
|
||
When =emms-player-mpd= opens a connection to =mpd=, =mpd= responds with a
|
||
message of the form "OK MPD 0.23.5". Neither =emms-player-mpd= nor its support
|
||
library =tq= anticipate the "OK MPD 0.23.5" message, but send such messages to a
|
||
new intrusive buffer called =*spurious*=. Listing [[lst:taming-spurious-buffers]]
|
||
makes those =*spurious*= buffers less intrusive. See:
|
||
1. [[info:elisp#The Zen of Buffer Display][The Zen of Buffer Display (info)]]
|
||
2. [[https://e17i.github.io/articles-emacs-display-1/][Configuring the Emacs display system]]
|
||
for technical information.
|
||
|
||
#+caption[Taming =*spurious*= buffers]:
|
||
#+caption: Taming =*spurious*= buffers.
|
||
#+name: lst:taming-spurious-buffers
|
||
#+begin_src emacs-lisp
|
||
(with-eval-after-load 'emms-player-mpd
|
||
;; https://stackoverflow.com/a/47587185 answers:
|
||
;; How to avoid pop-up of *Async Shell Command* buffers in Emacs?
|
||
;; Avoid popping up of `*spurious*' buffers:
|
||
(add-to-list 'display-buffer-alist
|
||
'("\\*spurious\\*.*"
|
||
(display-buffer-at-bottom)
|
||
(window-height . fit-window-to-buffer))))
|
||
#+end_src
|
||
|
||
*** [[https://www.musicpd.org/][Music Player Daemon]] configuration configuration
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:mpd-configuration-file
|
||
:END:
|
||
|
||
Listing [[lst:make-mpd-conf]] proposes a [[https://www.musicpd.org/][Music Player Daemon]] configuration file that
|
||
keeps each new connection for a day in order to reduce the rate of =*spurious*=
|
||
generation.
|
||
|
||
#+Caption[A Music Player Daemon configuration file proposal]:
|
||
#+caption: A Music Player Daemon configuration file proposal.
|
||
#+name: lst:make-mpd-conf
|
||
#+begin_src shell :results silent
|
||
case "$(uname -s)" in
|
||
Darwin)
|
||
cat <<EOF > ~/.mpd/mpd.conf
|
||
music_directory "~/Music"
|
||
playlist_directory "~/.mpd/playlists"
|
||
db_file "~/.mpd/mpd.db"
|
||
log_file "~/.mpd/mpd.log"
|
||
pid_file "~/.mpd/mpd.pid"
|
||
state_file "~/.mpd/mpdstate"
|
||
follow_outside_symlinks "yes"
|
||
follow_inside_symlinks "yes"
|
||
|
||
bind_to_address "localhost"
|
||
port "6600"
|
||
connection_timeout "86400"
|
||
|
||
audio_output {
|
||
type "osx"
|
||
name "CoreAudio"
|
||
mixer_type "software"
|
||
}
|
||
EOF
|
||
;;
|
||
esac
|
||
#+end_src
|
||
|
||
* [[info:emacs#Init File][Init File (info)]] footer
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:user-init-file-footer
|
||
:END:
|
||
|
||
#+caption[Tangle the =user-init-file= footer]:
|
||
#+caption: Tangle the =user-init-file= footer.
|
||
#+name: lst:tangle-user-init-file-footer
|
||
#+begin_src emacs-lisp
|
||
(provide 'init)
|
||
|
||
;; Emacs looks for "Local variables:" after the last "newline-formfeed".
|
||
|
||
;; Local Variables:
|
||
;; indent-tabs-mode: nil
|
||
;; End:
|
||
;;; init.el ends here
|
||
#+end_src
|
||
|
||
* Local variables linking to [[#sec:latexmk-save-compile-display-loop][Latexmk save-compile-display-loop]]
|
||
:PROPERTIES:
|
||
:CUSTOM_ID: sec:local-variables
|
||
:END:
|
||
|
||
Only the [[info:org#Top][Org]] source file shows the local variables footer.
|
||
|
||
\printbibliography
|
||
|
||
# Emacs looks for "Local variables:" after the last "newline-formfeed".
|
||
|
||
# Local Variables:
|
||
# compile-command: "latexmk -interaction=nonstopmode -lualatex -pvc -shell-escape README.tex"
|
||
# eval: (org-eval-emacs-lisp-setup-blocks)
|
||
# fill-column: 80
|
||
# End:
|