pprevos/emacs-writing-studio

#+title: Emacs Writing Studio #+author: Peter Prevos

/Emacs Writing Studio/ (EWS) by Peter Prevos is a configuration and comprehensive manual for writers seeking an integrated research, writing, and publication tool. The EWS book discusses everything from researching and organising ideas and writing without distractions to publishing in multiple formats. EWS is useful to beginners and experienced Emacs users, offering practical tips and a tailored configuration to enhance your writing process.

This repository contains the Emacs configuration plus the Org source files for the EWS book.

#+attr_html: :alt Emacs Writing Studio logo :title Emacs Writing Studio logo :width 400 #+attr_org: :width 200 [[file:emacs-writing-studio.png]]

If you like to support my work, then please purchase the EWS e-book or paperback from your [[https://books2read.com/b/4NpgQ9][favourite book retailer]] or download from [[https://payhip.com/b/alhIJ][PayHip]] or [[https://leanpub.com/emacswritingstudio][LeanPub]].

The EWS book is written and produced with the EWS configuration and some other software listed below. The Org mode source code of the book is freely available in the =documents= folder, so you can also 'roll your own' with the Org export functionality and associated external software.

The [[https://lucidmanager.org/tags/emacs][EWS website]] is the forerunner of the book and explains the configuration. There is also a [[https://www.youtube.com/playlist?list=PLGx4TR_jvOQDIT878vGDe1ElUlij3UEKI][YouTube playlist]] that demonstrates how to use /Emacs Writing Studio/.

This repository is not a maintained Emacs package. It provides a starting point to develop a configuration for beginning Emacs users. 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.

The EWS configuration follows the following principles:

• Stay as close as humanly bearable to vanilla GNU Emacs
• Leverage functionality of the latest Emacs version
• Standard keyboard shortcuts
• No configuration for writing code (prog-mode)
• Centred around Org mode
• No-code configuration (customisation tool instead of writing Emacs Lisp)

Feel free to raise an issue if you have any suggestions on how to enhance the configuration, like to include additional packages useful to authors or fix some typos in the text.

• EWS Workflow The EWS configuration, associated website and book follow a basic workflow for authoring documents, visualised below.

#+attr_html: :width 600 [[file:documents/images/emacs-workflow.png]]

• /Inspiration/ relates to reading, listening to and watching media such as e-books or lectures. Emacs can maintain and consume your bibliography or media collection.
• /Ideation/ is the phase where we reflect on the ideas of others and develop our own. Emacs acts as a note-taking system in this phase.
• /Production/ is the actual writing phase. EWS focuses on the capabilities of the Org mode package for writing projects.
• /Publication/ is the last phase in which Org mode files are converted to the final product in ePub, PDF or office format.

Another part of being a researcher and writer is /Administration/, which is not a phase in the process as such, but nevertheless essential. Administration in the EWS context relates to managing files and projects.

• Install EWS The =init.el= file contains the basic configuration and =ews.el= defines a series of convenience functions.

To install the EWS configuration, download the =init.el= and =ews.el= files from this GitHub repository and save them in the configuration folder. The location of the configuration folder depends on your operating system and Emacs version. Type =C-h v user-emacs-directory= to identify its location in the popup help buffer. + EWS activates and installs the required packages after you evaluate the restart-emacs function or the next time you start the program.

Experienced Emacs users, can try EWS configuration, without clobbering your existing configuration:

#+begin_src shell git clone https://github.com/pprevos/emacs-writing-studio emacs --init-directory emacs-writing-studio #+end_src

• Supporting Applications Emacs is not only a text editor but also an interface to other software. EWS interface with software that Emacs uses for various tasks.

When EWS starts and some of the listed software is missing, the =Messages= buffer will list any missing software. The core functionality of Emacs will work fine without this software, but some specialised tasks require assistance from this software.

Methods on installing these packages depend on your operating system.

Some of the listed packages are alternatives for each other, so you only need to install one of them.

** Inspiration

• gs ([[https://www.ghostscript.com/][GhostScript]]) or mutool ([[https://mupdf.com/][MuPDF]]): View PDF files
• pdftotext ([[https://poppler.freedesktop.org/][poppler-utils]]): Convert PDF to text (enable search)
• soffice ([[https://www.libreoffice.org/][LibreOffice]]): View and create office documents
• zip: Unpack ePub documents
• ddjvu ([[http://djvu.org/][DjVuLibre]]): View DjVu files
• curl: Reading RSS feeds
• mpg321, ogg123 ([[https://www.xiph.org/][vorbis-tools]]), mplayer, mpv, or vlc: Play music and watch videos

** Ideation

• grep or ripgrep: Search inside files

** Production

• hunspell: Spellcheck. Also requires a hunspell dictionary
• dvipng: Preview mathematical notation (part of LaTeX)
• git: Version control

** Publication

• convert ([[https://imagemagick.org/][ImageMagick]]) or =gm= ([[http://www.graphicsmagick.org/][GraphicsMagick]]): Convert image files
• latex ([[https://www.latex-project.org/get/][TexLive, MacTex or MikTeX]]): Preview LaTeX and export Org to PDF
• zip: Create ePub and office documents

• Compiling the EWS book This repository contains the Org mode source files for the /Emacs Writing Studio/ book. The source files are optimised for export to PDF (using LaTeX) and ePub.

To compile the book as a PDF, ePub you need the EWS configuration and the required supporting applications listed above. You will also need the [[https://graphviz.org/][Graphviz]] software, which draws some of the diagrams used in the book. Run the Org export function from inside the =00-emacs-writing-studio.org= file to generate the book.