99 부록 닷파일 설명
This appendix presents and explains the Emacs Writing Studio (EWS) configuration. The configuration is annotated to explain the logic of the code and provides some options for enhancements or additional functionality. This configuration follows the following principles:
- Leverage functionality of the latest version of GNU Emacs
- Minimalist configuration
- Use standard keyboard shortcuts
- Centred around Org mode
- No configuration for writing code
This configuration is a starting point for your Emacs journey. Feel free to modify any part of the EWS initialisation file and study its effects. You can find the latest version of this configuration on GitHub:
github.com/pprevos/emacs-writing-studioThis repository is not actively maintained. For beginning Emacs users, the configuration acts as a starting point to develop a configuration. More advanced users can copy ideas. The code will only be updated when there are bugs due to future changes in packages or Emacs itself.
;;; init.el --- Emacs Writing Studio init -*- lexical-binding: t; -*-
;; Copyright (C) 2024 Peter Prevos
;; Author: Peter Prevos <peter@prevos.net>
;; Maintainer: Peter Prevos <peter@prevos.net>
;; URL: https://github.com/pprevos/emacs-writing-studio/
;;
;; This file is NOT part of GNU Emacs.
;;
;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
;;
;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; GNU General Public License for more details.
;;
;; You should have received a copy of the GNU General Public License
;; along with this program. If not, see <https://www.gnu.org/licenses/>.
;;
;;; Commentary:
;;
;; Emacs Writing Studio init file
;; https://lucidmanager.org/tags/emacs
;;
;; This init file is tangled from the Org mode source:
;; documents/ews-book/99-appendix.org
;;
;;; Code:Using EWS
The first part of the configuration sets the basic principles of the EWS configuration, such as package management, the user interface look and feel, the minibuffer completion system and basic settings to enable writing for humans.
Basic configuration
The first part of the configuration checks if the latest version of Emacs is running. EWS leverages some of the newest functionality, so you must install this version. Note that the expression or higher (< emacs-major-version 29) is in Polish notation. In Lisp, the operator is placed before the operands, unlike the more common infix notation, which places the operator between the operands, e.g. emacs-major-version < 29.
;; Emacs 29 avaibale? (when (< emacs-major-version 29)
(error "Emacs Writing Studio requires Emacs version 29 or later"))Any changes made by the Emacs customisation system in EWS are stored in custom.el instead of directly to the init file. This approach prevents the customisation system from modifying the initialisation file. The custom.el file is loaded when found. If variables are set in both the custom and the init files, the init.el file takes preference.
;; Custom settings in a separate file and load the custom settings (setq-default custom-file (expand-file-name "custom.el" user-emacs-directory))
(load custom-file :no-error-if-file-is-missing)Keyboard shortcuts defined in EWS all use the C-c w prefix. Access the customise-variable function with the C-c w v shortcut.
(keymap-global-set "C-c w v" 'customize-variable)Emacs packages
Emacs users have developed and shared thousands of packages with the rest of the community. These packages are written in Emacs Lisp and extend its capabilities. This part of the configuration sets the essential elements to load and install packages from the MELPA archive (melpa.org).
;; Set package archives (use-package package
:config
(add-to-list 'package-archives
'("melpa" . "https://melpa.org/packages/"))
(package-initialize))This configuration implements John Wiegley’s Use-Package. This package simplifies installing and configuring packages with a standardised and easy-to-read method. Software developers call such a tool ‘syntactic sugar’, which is syntax designed to make code easier to read or write, making the language “sweeter” for humans (Landin 1964).
The Use-Package system consists of a set of statements between parenthesis, which is a macro. In its simplest form, it is something like (use-package <package-name>). The code can also contain one or more sections to set various options. The :custom section below sets three variables. These variables enact three protocols. Any missing package is automatically installed from its online source, and the source code is compiled to speed up Emacs. Thirdly, compilation warnings are kept to a minimum so as not to scare beginning users with log files.
;; Package Management (use-package use-package
:custom
(use-package-always-ensure t)
(package-native-compile t)
(warning-minimum-level :emergency))To read the finer details of the Use-Package macro, read the manual with C-h R use-package.
Emacs Writing Studio functionality
EWS also provides a range of bespoke convenience functions for various aspects of the writing process. Ensure you download this file from the EWS repository.
;; Load EWS functions (load-file (concat (file-name-as-directory user-emacs-directory) "ews.el"))The ews-missing-executables function checks if external software is available on your system. Emacs writes a message in the minibuffer if any of the recommended tools are missing. You can jump to the Messages buffer with C-h e to review the output. Emacs will function normally when this software is unavailable, but some features might not work.
The input for this function is a list, a series of strings between parenthesis that starts with a tick symbol: '("this" "is" "a" "list") The tick prevents Emacs from confusing the list of data with a function. In this function, some lists also contains other lists.
This function checks whether all these packages are available on your system. For software in a nested list, such as ("convert" "gm"), only one of them has to be available, as these programs are alternatives for the same functionality.
;; Check for missing external software
;;
;; - soffice (LibreOffice): View and create office documents
;; - zip: Unpack ePub documents
;; - pdftotext (poppler-utils): Convert PDF to text
;; - ddjvu (DjVuLibre): View DjVu files
;; - curl: Reading RSS feeds
;; - convert (ImageMagick) or gm (GraphicsMagick): Convert image files ;; - latex (TexLive, MacTex or MikTeX): Preview LaTex and export Org to PDF
;; - hunspell: Spellcheck. Also requires a hunspell dictionary
;; - grep: Search inside files
;; - gs (GhostScript) or mutool (MuPDF): View PDF files
;; - mpg321, ogg123 (vorbis-tools), mplayer, mpv, vlc: Media players
;; - git: Version control (ews-missing-executables
'("soffice"
"zip"
"pdftotext"
"ddjvu"
"curl"
("convert" "gm")
"latex"
"hunspell"
"grep"
("gs" "mutool")
("mpg321" "ogg123" "mplayer" "mpv" "vlc")
"git"))Look and feel
EWS espouses a minimalist aesthetic to provide a distraction-free environment. The first three lines of code disable the toolbar, the menu bar, and the scroll bar. The menu bar can be useful for beginners, and you can still access it with the F10 key. If you like to keep the tool, menu, and/or scroll bars, then either remove the relevant lines, change the -1 to a 1, or add two semicolons at the start of the relevant lines to convert them to comments.
;;; LOOK AND FEEL (tool-bar-mode -1)
(menu-bar-mode -1)
(scroll-bar-mode -1)Vanilla Emacs has the slightly paternalistic habit of requiring a single y or n answer, while on some occasions, it requires you to type yes or no, due to the perceived higher risk of typing the wrong answer. The setq function sets the use-short-answers variable to t. If you want to retain this behaviour, change the t to nil.
In Emacs Lisp, t means TRUE and nil is equivalent to FALSE. Emacs documentation often mentions setting a value to “non-nil”, which is a double negative to suggest setting the variable to true.
;; Short answers only please (setq-default use-short-answers t)The next two sections of code further improve the Emacs interface with two packages by Emacs guru Protesilaos Stavrou.
The spacious padding package creates space around windows, preventing crammed text on your screen. The :init section contains code Emacs evaluates when loading the package. In this case, it enables the Spacious Padding mode. The :custom section also sets the line spacing to a more generous value. You can read the manual for this mode with C-h R spacious.
This configuration also modifies the line-spacing variable to create some space between logical lines. This variable is not part of the Spacious Padding package.
;; Spacious padding (use-package spacious-padding
:custom
(line-spacing 3)
:init
(spacious-padding-mode 1))The next package sets the Emacs theme. A theme is a set of configurations for fonts and colours. Themes are available in two types: light or dark background.
The Modus themes package is highly configurable. This Use-Package declaration contains a three sections. The :custom section customises variables used in the package. In this case, we instruct the package to use italic and bold fonts for emphasis and allow for fonts with fixed and variable pitch. The code also slightly increases the size of headings. You can toggle between a dark and a light version of this theme, and the last variable defines which to toggle between. EWS uses the tinted version of the themes, which you can modify.
The :custom section of the macro sets some variables to define fonts. This section also defines which themes are toggled when switching between light and dark themes with C-c w t t. The default is the tinted versions. If you want your configuration to default to the high-contrast versions or one of the two colour blindness-safe versions, customise the modus-themes-to-toggle variable. To see the possible options for the Modus themes, use the help file: C-h v modus-themes-collection.
The following section binds some keys to commands to toggle between dark and light or select any available modus themes. All EWS custom keybindings start with C-c w as the prefix key and C-c w t as the prefix key for the theme-related functions. You can obviously change these to suit your preferences. Read the Modus Themes package manual for details with C-h R modus.
The consult-theme command invoke the consult package to help you select between installed themes.
As a bonus, this code also installs Port’s Ef-Themes package, which is a wonderful collection of light and dark themes.
To set a default theme, run the customize-themes command and select your preferred version. Click the button to store your chosen default in the custom.el file
;; Modus and EF Themes (use-package modus-themes
:custom
(modus-themes-italic-constructs t)
(modus-themes-bold-constructs t)
(modus-themes-mixed-fonts t)
(modus-themes-to-toggle '(modus-operandi-tinted modus-vivendi-tinted))
:bind
(("C-c w t t" . modus-themes-toggle)
("C-c w t m" . modus-themes-select)
("C-c w t s" . consult-theme)))
(use-package ef-themes)The next section hooks the Variable Pitch mode to any Org buffer. This means that written prose is displayed in variable pitch, while metadata, code and other items are in fixed pitch. A hook is a construction in Emacs that associates modes with each other. In this case, variable pitch text is enabled for all text mode buffers.
;; Mixed-pich mode (use-package mixed-pitch
:hook
(org-mode . mixed-pitch-mode))This last code snippet in the look-and-feel section changes how Emacs automatically split windows to favour vertical splits over horizontal ones to improve readability. This section also installs the Balanced Windows package, which manages window sizes automatically. For example, when you have three open windows and you close one, the remaining windows each get half the screen.
;; Window management
;; Split windows sensibly (setq split-width-threshold 120
split-height-threshold nil) ;; Keep window sizes balanced (use-package balanced-windows
:config
(balanced-windows-mode))Minibuffer completion
EWS uses the Vertico-Orderless-Marginalia stack of minibuffer completion packages in their standard configuration. Chapter [BROKEN LINK: chap-ews] explains how to use minibuffer completion.
;; MINIBUFFER COMPLETION
;; Enable vertico (use-package vertico
:init
(vertico-mode)
:custom
(vertico-sort-function 'vertico-sort-history-alpha)) ;; Persist history over Emacs restarts. (use-package savehist
:init
(savehist-mode)) ;; Search for partial matches in any order (use-package orderless
:custom
(completion-styles '(orderless basic))
(completion-category-defaults nil)
(completion-category-overrides
'((file (styles partial-completion))))) ;; Enable richer annotations using the Marginalia package (use-package marginalia
:init
(marginalia-mode))Keyboard shortcuts menu
The Which-Key package improves the discoverability of keyboard shortcuts with a popup in the minibuffer.
Due to the naming conventions in Emacs, most functions start with the package name, so some can be long. The problem is that the most interesting part of a function name is at the end of the string, so we don’t want that to be hidden. This configuration widens the columns a bit to prevent truncated function names. This configuration also instructs Which-Key to order the list by function name rather than by key.
;; Improve keyboard shortcut discoverability (use-package which-key
:config
(which-key-mode)
:custom
(which-key-max-description-length 40)
(which-key-lighter nil)
(which-key-sort-order 'which-key-description-order))Improved help functionality
Emacs is advertised as a “self-documenting text editor”. While this is not entirely correct (if only computer code could document itself), every aspect of Emacs is documented within the source code.
Emacs has two levels of help. Firstly, there are the manuals for Emacs itself and some of the packages. Also each individual command and function contains documentation. The Helpful package by Wilfred Hughes adds contextual information to the built-in Emacs help. For example, when asking for documentation about a variable, the help file links to its customisation screen or the source code.
;; Improved help buffers (use-package helpful
:bind
(("C-h f" . helpful-function)
("C-h x" . helpful-command)
("C-h k" . helpful-key)
("C-h v" . helpful-variable)))Configure text modes
Emacs is principally designed for developing computer code, so it needs some modifications to enable writing text for humans. The config first ensures that Emacs does not try to install Text-Mode as a package, because it is buult-in.
Secondly, we hook Visual Line Mode to Text Mode. Visual Line mode wraps long lines to the nearest word to fit in the current window, as is common in word processing software.
By default, Emacs does not replace text when you select a section and start typing, which is unusual behaviour when writing prose. The :init section enables a more common default so that selected text is deleted when typed over. The :custom section enables the page-up and page-down keys to scroll to the top or bottom of a buffer. This section also redefines the way Emacs defines a sentence (refer to section [BROKEN LINK: sec-count]). The last variable saves any existing clipboard text into the kill ring for better operability between the operating system’s clipboard and Emacs’s kill ring.
;;; Text mode settings (use-package text-mode
:ensure
nil
:hook
(text-mode . visual-line-mode)
:init
(delete-selection-mode t)
:custom
(sentence-end-double-space nil)
(scroll-error-top-bottom t)
(save-interprogram-paste-before-kill t))Spellchecking
Writing without automated spell-checking would be quite annoying, even for the most experienced authors. The Flyspell package interfaces with the Hunspell software and the relevant dictionary to check spelling on the fly.
You must change the standard dictionary to your local variety with the ews-hunspell-dictionaries variable. EWS uses this particular variable because the dictionaries are set in two places to enable multilingual spelling. You can set multiple dictionaries for the same buffer. In my configuration I use "en_AU,nl_NL" so I can write in either the Australian variant of English of Dutch without having to change dictionaries. Section [BROKEN LINK: sec-spelling] explains how to use this package.
;; Check spelling with flyspell and hunspell (use-package flyspell
:custom
(ispell-program-name "hunspell")
(ispell-dictionary ews-hunspell-dictionaries)
(flyspell-mark-duplications-flag nil) ;; Writegood mode does this
(org-fold-core-style 'overlays) ;; Fix Org mode bug
:config
(ispell-set-spellchecker-params)
(ispell-hunspell-add-multi-dic ews-hunspell-dictionaries)
:hook
(text-mode . flyspell-mode)
:bind
(("C-c w s s" . ispell)
("C-;" . flyspell-auto-correct-previous-word)))Ricing Org mode
This part of the configuration sets a bunch of variables to improve the design of Org buffers. To learn what these variables do, use C-h v and enter the variable name.
Org has a plethora of variables to change its interface. You can add other variables or remove some to make Org look how you prefer. For example, to enable alphabetical lists and numerals, you must customise the org-list-allow-alphabetical variable to t. This adds a., A., a) and A) as additional options to number a list.
;;; Ricing Org mode (use-package org
:custom
(org-startup-indented t)
(org-hide-emphasis-markers t)
(org-startup-with-inline-images t)
(org-image-actual-width '(450))
(org-fold-catch-invisible-edits 'error)
(org-pretty-entities t)
(org-use-sub-superscripts "{}")
(org-id-link-to-org-use-id t)
(org-fold-catch-invisible-edits 'show))The above code snippet hides emphasis markers from view for an uncluttered screen. Emphasis markers are the symbols used to indicate italics, bold and other font decorations, for example _italic_. Hiding the syntax of a plain text document is not ideal because it obfuscates essential information. The Org Appear package by Alice P. Hacker shows hidden markers in Org buffers when the cursor is used for an emphasised word, giving us the best of both worlds.
;; Show hidden emphasis markers (use-package org-appear
:hook
(org-mode . org-appear-mode))The Org Fragtog package is similar to Org Appear but for LaTeX snippets. It automatically toggles Org mode LaTeX fragment previews as the cursor enters and exits them. By default, the text is small and can become unreadable when changing between dark and light themes.
The org-format-latex-options variable controls the way Emacs presents fragments. This variable is a list with properties such as colours and size. The plist-put function lets you change options in the list. The foreground and background are set to take the same colour as your text. If you change from dark to light mode or vice versa, you should evaluate the org-latex-preview function (C-c C-x C-l) to change the preview images.
Automated LaTeX previews are disabled because they can delay loading a page and cause trouble when the user does not have LaTeX installed.
;; LaTeX previews (use-package org-fragtog
:after org
:hook
(org-mode . org-fragtog-mode)
:custom
(org-startup-with-latex-preview nil)
(org-format-latex-options
(plist-put org-format-latex-options :scale 2)
(plist-put org-format-latex-options :foreground 'auto)
(plist-put org-format-latex-options :background 'auto)))The last package to modify Org buffers is Org Modern. However, most of the features have been switched off because it might be better for beginning users not to hide semantic symbols. You can experiment with changing these settings to change the look and feel of Org buffers.
;; Org modern: Most features are disabled for beginning users (use-package org-modern
:hook
(org-mode . org-modern-mode)
:custom
(org-modern-table nil)
(org-modern-keyword nil)
(org-modern-timestamp nil)
(org-modern-priority nil)
(org-modern-checkbox nil)
(org-modern-tag nil)
(org-modern-block-name nil)
(org-modern-keyword nil)
(org-modern-footnote nil)
(org-modern-internal-target nil)
(org-modern-radio-target nil)
(org-modern-statistics nil)
(org-modern-progress nil))Inspiration
Read e-books
The built-in Doc-View package can read various file formats with the assistance of external software. This configuration increases the resolution of the generated image file and raises the threshold for warning before opening large files to fifty MB (\(50 \times 2^{20}\)). Section [BROKEN LINK: sec-pdf] explains how to use this package.
Reading PDF files requires the GhostScript or MuPDF package. When the Poppler package is available, you can convert a PDF to text for easier searching and copying. To view DjVu files, you need the DjVuLibre library to parse them.
;; INSPIRATION
;; Doc-View (use-package doc-view
:custom
(doc-view-resolution 300)
(large-file-warning-threshold (* 50 (expt 2 20))))The Nov package by Vasilij Schneidermann provides valuable functionality for viewing ePub books inside Emacs. The init section ensures that any file with an epub extension is associated with this package. An ePub file is essentially a compressed website, so you will need the Zip program to enable reading these files. Refer to section [BROKEN LINK: sec-epub] on how to read ePub files.
;; Read ePub files (use-package nov
:init
(add-to-list 'auto-mode-alist '("\\.epub\\'" . nov-mode)))Emacs can read documents produced by standard office software. To achieve this, it converts these files to PDF with LibreOffice and presents them as such.
A confirmed bug in Org mode (version 9.6.15) overrides the associations between LibreOffice and Doc View mode. The code below is a workaround for reinstating the desired behaviour and associating the various file extensions with Doc View. This bug fix is optional if you use Org 9.7 and beyond.
;; Reading LibreOffice files
;; Fixing a bug in Org Mode pre-9.7
;; Org mode clobbers associations with office documents (use-package ox-odt
:ensure nil
:config
(add-to-list 'auto-mode-alist
'("\\.\\(?:OD[CFIGPST]\\|od[cfigpst]\\)\\'"
. doc-view-mode-maybe)))Bibliographies
These lines of code add two field types to BibTeX entries: keywords to help you order your literature and a link to a file so you can read any attachments in Emacs.
The ews-register-bibtex function assigns all .bib files in the ews-bibliography-directory variable to the list of global BibTeX files. You need to set this variable to the location where you store your bibliography. Section [BROKEN LINK: sec-bib] explains creating and managing a bibliography. We use a special variable to ensure other variables have the same value.
;; Managing Bibliographies (use-package bibtex
:custom
(bibtex-user-optional-fields
'(("keywords" "Keywords to describe the entry" "")
("file" "Relative or absolute path to attachments" "" )))
(bibtex-align-at-equal-sign t)
:config
(ews-bibtex-register)
:bind
(("C-c w b r" . ews-bibtex-register)))The Biblio package enables you to extract literature from various databases.
;; Biblio package for adding BibTeX records (use-package biblio
:bind
(("C-c w b b" . ews-bibtex-biblio-lookup)))Citar is the workhorse package for managing a bibliography and citations. It provides an interface between your text and the bibliography.
;; Citar to access bibliographies (use-package citar
:defer t
:custom
(citar-bibliography ews-bibtex-files)
:bind
(("C-c w b o" . citar-open)))Reading websites
The Elfeed package helps with reading RSS files, and the Elfeed-Org package lets you configure RSS feeds with an Org file. The EWS repository contains an example file. Read section [BROKEN LINK: sec-rss] for more information on how to use this tool. Elfeed uses the cURL software to download feeds. If this software is unavailable, it will use a slower version built into Emacs.
;; Read RSS feeds with Elfeed (use-package elfeed
:custom
(elfeed-db-directory
(expand-file-name "elfeed" user-emacs-directory))
(elfeed-show-entry-switch 'display-buffer)
:bind
("C-c w e" . elfeed)) ;; Configure Elfeed with org mode (use-package elfeed-org
:config
(elfeed-org)
:custom
(rmh-elfeed-org-files
(list (concat (file-name-as-directory (getenv "HOME")) "elfeed.org"))))The Org-Webtools package makes it easy to insert hyperlinks by converting the content of the kill ring to an Org hyperlink.
;; Easy insertion of weblinks (use-package org-web-tools
:bind
(("C-c w w" . org-web-tools-insert-link-for-url)))Playing multimedia files
The EMMS (Emacs MultiMedia System) package provides an interface to various multimedia players. You need one of these programs installed: mpg321, ogg123 (vorbis-tools), mplayer, mpv, or VLC.
;; Emacs Multimedia System (use-package emms
:config
(require 'emms-setup)
(require 'emms-mpris)
(emms-all)
(emms-default-players)
(emms-mpris-enable)
:custom
(emms-browser-covers #'emms-browser-cache-thumbnail-async)
:bind
(("C-c w m b" . emms-browser)
("C-c w m e" . emms)
("C-c w m p" . emms-play-playlist )
("<XF86AudioPrev>" . emms-previous)
("<XF86AudioNext>" . emms-next)
("<XF86AudioPlay>" . emms-pause)))Opening files with external software
The OpenWith package by Markus Trisk lets you open files in external software. Refer to sections [BROKEN LINK: sec-openwith] and [BROKEN LINK: sec-find-notes] for further details.
(use-package openwith
:config
(openwith-mode t)
:custom
(openwith-associations nil))Ideation
Org capture
The possibilities for capture templates are extensive and depend on your use cases. This configuration is only an example of the options. The Org documentation provides lots of detail (C-h R org <ret> capture). You will also need to customise the org-default-notes-file variable.
;; Fleeting notes (use-package org
:bind
(("C-c c" . org-capture)
("C-c l" . org-store-link))
:custom
(org-goto-interface 'outline-path-completion)
(org-capture-templates
'(("f" "Fleeting note"
item
(file+headline org-default-notes-file "Notes")
"- %?")
("p" "Permanent note" plain
(file denote-last-path)
#'denote-org-capture
:no-save t
:immediate-finish nil
:kill-buffer t
:jump-to-captured t)
("t" "New task" entry
(file+headline org-default-notes-file "Tasks")
"* TODO %i%?"))))Denote
Denote is a flexible note-taking and file management package. Refer to [BROKEN LINK: sec-denote] or the extensive Denote manual with C-h R denote. At a minimum, you need to configure the denote-directory variable to indicate the location of your notes.
The EWS package includes a convenience function to improve how Denote displays links to attachments, linked to the denote-link-description-function.
;; Denote (use-package denote
:defer t
:custom
(denote-sort-keywords t)
(denote-link-description-function #'ews-denote-link-description-title-case)
:hook
(dired-mode . denote-dired-mode)
:custom-face
(denote-faces-link ((t (:slant italic))))
:init
(require 'denote-org-extras)
:bind
(("C-c w d b" . denote-find-backlink)
("C-c w d d" . denote-date)
("C-c w d l" . denote-find-link)
("C-c w d h" . denote-org-extras-link-to-heading)
("C-c w d i" . denote-link-or-create)
("C-c w d k" . denote-rename-file-keywords)
("C-c w d n" . denote)
("C-c w d r" . denote-rename-file)
("C-c w d R" . denote-rename-file-using-front-matter)))The Consult package provides some convenience functionality to make life easier.
The consult-org-heading command provides a table of contents of the Org mode file to quickly move around a large file. The consult-grep function lets you search through files in the current directory. The search functionality requires access to the Grep software.
Consult has a lot more functionality that replaces some base Emacs commands with more convenient version. Most of these have not been enabled to ensure we stay as close as possible to vanilla Emacs. The Consult online documentation provides detailed descriptions of these enhanced commands.
;; Consult convenience functions (use-package consult
:bind
(("C-c w h" . consult-org-heading)
("C-c w g" . consult-grep)))Consult Notes is a convenience package that builds on Consult. It provides access to Denote files and also lets you search through your notes.
;; Consult-Notes for easy access to notes (use-package consult-notes
:bind
(("C-c w d f" . consult-notes)
("C-c w d g" . consult-notes-search-in-all-notes))
:init
(consult-notes-denote-mode))The Citar-Denote package lets you create a many-to-many relationship between your Denote notes and items in your bibliography (section [BROKEN LINK: sec-citar-denote]).
;; Citar-Denote to manage literature notes (use-package citar-denote
:custom
(citar-open-always-create-notes t)
:init
(citar-denote-mode)
:bind
(("C-c w b c" . citar-create-note)
("C-c w b n" . citar-denote-open-note)
("C-c w b x" . citar-denote-nocite)
:map org-mode-map
("C-c w b k" . citar-denote-add-citekey)
("C-c w b K" . citar-denote-remove-citekey)
("C-c w b d" . citar-denote-dwim)
("C-c w b e" . citar-denote-open-reference-entry)))The Denote-Explore package provides convenience functions to manage your collection of notes and attachments (section [BROKEN LINK: sec-denote-explore]).
;; Explore and manage your Denote collection (use-package denote-explore
:bind
(;; Statistics
("C-c w x c" . denote-explore-count-notes)
("C-c w x C" . denote-explore-count-keywords)
("C-c w x b" . denote-explore-barchart-keywords)
("C-c w x e" . denote-explore-barchart-filetypes)
;; Random walks
("C-c w x r" . denote-explore-random-note)
("C-c w x l" . denote-explore-random-link)
("C-c w x k" . denote-explore-random-keyword)
("C-c w x x" . denote-explore-random-regex)
;; Denote Janitor
("C-c w x d" . denote-explore-identify-duplicate-notes)
("C-c w x z" . denote-explore-zero-keywords)
("C-c w x s" . denote-explore-single-keywords)
("C-c w x o" . denote-explore-sort-keywords)
("C-c w x w" . denote-explore-rename-keyword)
;; Visualise denote
("C-c w x n" . denote-explore-network)
("C-c w x v" . denote-explore-network-regenerate)
("C-c w x D" . denote-explore-degree-barchart)))Production
Managing the writing process
The EWS repository provides some Org-related convenience files for inserting notes, drawers, and counting words. At this stage, the screenshot command is experimental.
;; Set some Org mode shortcuts (use-package org
:bind
(:map org-mode-map
("C-c w n" . ews-org-insert-notes-drawer)
("C-c w p" . ews-org-insert-screenshot)
("C-c w c" . ews-org-count-words)))The Olivetti package removes distractions from the screen and converts your Emacs session to an electronic typewriter. The ews-olivetti function stores the screen configuration before you activate the distraction-free writing mode. When you disable Olivetti mode with this function then the original configuration is restored.
;; Distraction-free writing (use-package olivetti
:demand t
:bind
(("C-c w o" . ews-olivetti)))Undo-Tree provides a graphical view of the various versions of the current buffer.
;; Undo Tree (use-package undo-tree
:config
(global-undo-tree-mode)
:custom
(undo-tree-auto-save-history nil)
:bind
(("C-c w u" . undo-tree-visualise)))Citations
This configuration sets the global bibliography equal to the ews-bibtex-files variable. To set this variable, configure the ews-bibtex-directory to register bibliography files and run the ews-bibtex-register function every time you add new bib-files.
;; Export citations with Org Mode (require 'oc-natbib)
(require 'oc-csl)
(setq org-cite-global-bibliography ews-bibtex-files
org-cite-insert-processor 'citar
org-cite-follow-processor 'citar
org-cite-activate-processor 'citar)Quality assurance
Emacs can hook into the dictionary server at dict.org and the Powerthesaurus package integrates with powerthesaurus.org. Refer to section [BROKEN LINK: sec-qa] for details.
;; Lookup words in the online dictionary (use-package dictionary
:custom
(dictionary-server "dict.org")
:bind
(("C-c w s d" . dictionary-lookup-definition))) (use-package powerthesaurus
:bind
(("C-c w s p" . powerthesaurus-transient)))The Writegood package helps to detect weasel words, passive writing, and repeated words. It also contains functions to estimate a text’s complexity using the Flesch-Kincaid test.
;; Writegood-Mode for weasel words, passive writing and repeated word detection (use-package writegood-mode
:bind
(("C-c w s r" . writegood-reading-ease)
("C-c w s l" . writegood-grade-level))
:hook
(text-mode . writegood-mode))The TitleCase package strives for the most accurate title-casing of sentences, lines, and regions of text in English prose. You can customise the titlecase-style variable
The EWS convenience function can do this for all headings in an Org file to ensure consistency (section [BROKEN LINK: sec-titlecase]).
;; Titlecasing (use-package titlecase
:bind
(("C-c w s t" . titlecase-dwim)
("C-c w s c" . ews-org-headings-titlecase)))Abbreviations
Abbrev mode is a built-in program that helps you speed up your writing by defining abbreviations and common spelling mistakes and automatically replacing them with words, sentences, or complete paragraphs.
;; Abbreviations (add-hook 'text-mode-hook 'abbrev-mode)The Lorem Ipsum generator can be helpful when designing a document’s layout. This package inserts dummy Latin text into a buffer.
;; Lorem Ipsum generator (use-package lorem-ipsum
:custom
(lorem-ipsum-list-bullet "- ") ;; Org mode bullets
:init
(setq lorem-ipsum-sentence-separator
(if sentence-end-double-space " " " "))
:bind
(("C-c w s i" . lorem-ipsum-insert-paragraphs)))Version control
The built-in Ediff package compares different files and shows their differences. It also lets you decide how to merge the two versions, like a tracked-changes function in a Word processor. The ediff family of functions does not split its windows nicely by default, so these settings make the program more straightforward to use.
Advanced version control requires a Version Control System, such as Git.
;; ediff (use-package ediff
:ensure nil
:custom
(ediff-keep-variants nil)
(ediff-split-window-function 'split-window-horizontally)
(ediff-window-setup-function 'ediff-setup-windows-plain))Other text in modes
Org is fantastic, but it is not the only text mode useful for authors. EWS installs both Markdown and Fountain. Refer to section [BROKEN LINK: sec-text-modes] for details.
;; Enable Other text modes
;; Fontain mode for writing scrits (use-package fountain-mode) ;; Markdown mode (use-package markdown-mode)Publication
Basic settings
This snippet sets some basic export settings for org mode. You can either set these as variable to apply them to all files by default, or insert them as keywords in your front matter.
Read the Export Settings section in to Org manual for a detailed description of the possible configurations.
The timestamp for exporting files is set to the European date format of day, month, and year. If you publish for American audiences, perhaps you like to modify the org-export-date-timestamp-format to "%B %e %Y". These letters stand for the full name of the month, the day number without leading zero, and the year in four digits. See the documentation of the format-time-string function for details on how to format dates in other methods.
;; PUBLICATION
;; Generic Org Export Settings (use-package org
:custom
(org-export-with-drawers nil)
(org-export-with-todo-keywords nil)
(org-export-with-toc nil)
(org-export-with-smart-quotes t)
(org-export-date-timestamp-format "%e %B %Y"))Epub
The ox-ePub package exports Org files to the most common e-book format. The ox-org export is required to enable exporting to Org to prevent issues with the table of contents (section [BROKEN LINK: sec-ox-epub]).
;; epub export (use-package ox-epub
:demand t
:init
(require 'ox-org))Latex
This configuration part defines the export process from Org to TeX to PDF. This setup also removes any temporary files created in the process. You will obviously need a working version of LaTeX with all relevant packages installed on your computer.
;; LaTeX PDF Export settings (use-package ox-latex
:ensure nil
:demand t
:custom
;; Multiple LaTeX passes for bibliographies
(org-latex-pdf-process
'("pdflatex -interaction nonstopmode -output-directory %o %f"
"bibtex %b"
"pdflatex -shell-escape -interaction nonstopmode -output-directory %o %f"
"pdflatex -shell-escape -interaction nonstopmode -output-directory %o %f"))
;; Clean temporary files after export
(org-latex-logfiles-extensions
(quote ("lof" "lot" "tex~" "aux" "idx" "log" "out"
"toc" "nav" "snm" "vrb" "dvi" "fdb_latexmk"
"blg" "brf" "fls" "entoc" "ps" "spl" "bbl"
"tex" "bcf"))))The next part defines the EWS document class, which is used to produce the paperback version of this book.
The first part of the code defines the name used in the Org file, in this case #+latex_class: ews. The next par is the preamble in LaTeX code. Note that backslashes need to be escaped by using two of them. Org also adds standard packages, read the documentation for org-latex-classes for details on how to modify the standard inclusions.
The last section defines how the heading levels in the Org file are translated to LaTeX commands. This code defines the first three Org heading levels.
;; EWS paperback configuration (with-eval-after-load 'ox-latex
(add-to-list
'org-latex-classes
'("ews"
"\\documentclass[11pt, twoside, hidelinks]{memoir}
\\setstocksize{9.25in}{7.5in}
\\settrimmedsize{\\stockheight}{\\stockwidth}{*}
\\setlrmarginsandblock{2cm}{1cm}{*}
\\setulmarginsandblock{1.5cm}{2.25cm}{*}
\\checkandfixthelayout
\\setcounter{tocdepth}{0}
\\OnehalfSpacing
\\usepackage{ebgaramond}
\\usepackage[htt]{hyphenat}
\\chapterstyle{bianchi}
\\setsecheadstyle{\\normalfont \\raggedright \\textbf}
\\setsubsecheadstyle{\\normalfont \\raggedright \\textbf}
\\setsubsubsecheadstyle{\\normalfont\\centering}
\\renewcommand\\texttt[1]{{\\normalfont\\fontfamily{cmvtt}
\\selectfont #1}}
\\usepackage[font={small, it}]{caption}
\\pagestyle{myheadings}
\\usepackage{ccicons}
\\usepackage[authoryear]{natbib}
\\bibliographystyle{apalike}
\\usepackage{svg}"
("\\chapter{%s}" . "\\chapter*{%s}")
("\\section{%s}" . "\\section*{%s}")
("\\subsection{%s}" . "\\subsection*{%s}")
("\\subsubsection{%s}" . "\\subsubsection*{%s}"))))Administration
Getting Things Done
The Org configuration for managing actions and projects sets a custom agenda item that shows the agenda for the next three days, a list of to-do items marked NEXT, and a list of items marked WAIT.
The org-agenda-custom-commands variable provides a highly flexible system for crafting agenda views. You could, for example, build an agenda for your private actions and one for your work (section [BROKEN LINK: sec-reflect]).
;;; ADMINISTRATION
;; Bind org agenda command and custom agenda (use-package org
:custom
(org-agenda-custom-commands
'(("e" "Agenda, next actions and waiting"
((agenda "" ((org-agenda-overriding-header "Next three days:")
(org-agenda-span 3)
(org-agenda-start-on-weekday nil)))
(todo "NEXT" ((org-agenda-overriding-header "Next Actions:")))
(todo "WAIT" ((org-agenda-overriding-header "Waiting:")))))))
:bind
(("C-c a" . org-agenda)))Manage files
The Dired package is a convenient and powerful tool for organising your drives and accessing your information. Dired lists files and directories in alphabetical order. I prefer a different view, which shows directories on top and files below them. The dired-listing-switches variable determines how files are displayed in a Dired buffer.
The dired-dwim-target variable instructs to guess a default target directory. This means that if a Dired buffer is displayed in some window, use that directory instead of this Dired buffer’s current directory.
The delete-by-moving-to-trash variable moves deleted files to the wastebasket instead of vanishing them into thin air.
The last line enables opening new directories in the same buffer as the current one (using the a key), preventing littering your session with Dired buffers. The first time you use this, Emacs asks you to confirm whether you would like to use this option.
;; FILE MANAGEMENT (use-package dired
:ensure
nil
:commands
(dired dired-jump)
:custom
(dired-listing-switches
"-goah --group-directories-first --time-style=long-iso")
(dired-dwim-target t)
(delete-by-moving-to-trash t)
:init
(put 'dired-find-alternate-file 'disabled nil))The default setting for Dired is to show hidden files, even though they are hidden for a reason. This configuration uses dired-omit-mode to remove these hidden files from view. You can toggle this behaviour with the full stop key.
;; Hide or display hidden files (use-package dired
:ensure nil
:hook (dired-mode . dired-omit-mode)
:bind (:map dired-mode-map
( "." . dired-omit-mode))
:custom (dired-omit-files "^\\.[a-zA-Z0-9]+"))The dired-narrow package provides some convenience functions to filter a Dired buffer by a search criterion or a regular expression.
(use-package dired-narrow)This next bit of configuration defines how Emacs manages automated backups. The default setting is that the system stores these files in the folder where the original files live, cluttering folders with copies of your stuff.
The setting below modifies the backup-directory-alist variable so that Emacs saves all backups (indicated by ".") in the bak subdirectory of your init folder. Alternatively, you could instruct Emacs not to save backups with (setq-default make-backup-files nil). I prefer keeping backups as they have saved my bacon a few times.
This configuration also eliminates lock files, which are only useful when working in shared folders. Lock files prevent other users from opening a file when another user is already editing it, but create a lot of clutter when writing by yourself. Change this variable to t if you collaborate with others or maintain fles on multiple systems through a file-sharing service such as Nextcloud.
;; Backup files (setq-default backup-directory-alist
`(("." . ,(expand-file-name "backups/" user-emacs-directory)))
version-control t
delete-old-versions t
create-lockfiles nil)Emacs saves a list of recent files using the recentf package. This package maintains a list of recently opened files and makes it easy to visit them. The recent files list is automatically saved across Emacs sessions. By default, the recent files mode stores the last twenty opened files, which you can change by adjusting the recentf-max-saved-items variable, which in EWS is fifty.
;; Recent files (use-package recentf
:config
(recentf-mode t)
:custom
(recentf-max-saved-items 50)
:bind
(("C-c w r" . recentf-open)))This last file package enables you to set bookmarks for your favourite locations. The bookmark-save-flag is set to one, so the bookmarks file is saved every time you add a new one. The default value only saves it when you exit Emacs, which means you could lose bookmarks in the unlikely event of an Emacs or system crash.
;; Bookmarks (use-package bookmark
:custom
(bookmark-save-flag 1)
:bind
("C-x r d" . bookmark-delete))Viewing images
Emacs has two modes for viewing and managing images. The image viewer shows individual images, but you can also browse through a directory with the left and right arrow keys.
To enable image manipulation, you will need to install ImageMagic.
Using C-<ret> opens an image in the Dired buffer in your favourite editor. The image-dired-external-viewer variable defines the program you use to edit pictures, in my case GIMP, the GNU Image Manipulation Program.
;; Image viewer (use-package emacs
:custom
(image-dired-external-viewer "gimp")
:bind
((:map image-mode-map
("k" . image-kill-buffer)
("<right>" . image-next-file)
("<left>" . image-previous-file))
(:map dired-mode-map
("C-<return>" . image-dired-dired-display-external))))The built-in Image-Dired package can generate thumbnails from within a Dired buffer and let you work on images from there.
(use-package image-dired
:bind
(("C-c w I" . image-dired))
(:map image-dired-thumbnail-mode-map
("C-<right>" . image-dired-display-next)
("C-<left>" . image-dired-display-previous)))